Field Guide
This section outlines the attributes for each of the objects exposed by the Webhooks API.
Understanding Scope for a Webhook
Webhooks are targeted to provide updates on specific range of data within a Hub. For example you could subscribe to file added event for a Project within a Hub or a sub folder within a Project. In Webhooks terminology, it is referred as scope of the Webhook. Scopes are recursive in nature i.e. if you choose your scope to be a Project, then you will get notification for all folders and sub-folders within the Project. Please note that, webhook only supports folder scope. A webhook can be registered on a Project with Root Folder scope and hence can receive callbacks for all events within that Project and its children.
Webhook
A webhook represents a registered callback URL in a system for a specific event. This callback URL will be called by the system when the event is triggered. Each webhook is defined within a scope where the event can be trigger.
Schema
Attribute | Description |
---|---|
hookId | Unique identifier of the webhook. |
event | Type of event that webhook was created for. |
system | Type of system where webhook was created. |
callbackUrl | URL called when the event type for this system happens. |
createdBy | Identifier of the creator. Service or user id. |
creatorType | Type of the creator of the webhook. It can be Application for 2-Legged Token and O2User for 3-Legged Token. |
scope | Extent to where the event will be triggered. Please refer to the individual event specification pages for valid scopes. For example, Data Management events. |
hookAttribute | JSON object that can be used by you to store/set some custom information. Maximum size of JSON object (content) should be less than 1KB. Object will be send back to you on callback payload. Check version added sample |
filter | JsonPath expression that can be used by you to filter the callbacks you receive based on the payload of the callback. Check version added sample |
urn | Unique identifier of the webhook in URN format. |
status | Status of the webhook. Possible values are: active , inactive and reactivated . |
hubId | Optional. Should be provided if the user may be a member of a large number of projects. This hub ID corresponds to an account ID in the BIM 360 API, prefixed by “b.” |
projectId | Optional. Should be provided if the user may be a member of a large number of projects. This project ID corresponds to the project ID in the BIM 360 API, prefixed by “b.” |
autoReactivateHook | Optional. Flag to enable the hook for the automatic reactivation flow. Default: false .
Please see Event Delivery Guarantees for more details. |
hookExpiry | Optional. ISO8601 formatted date and time when the hook should expire and automatically be deleted. Default: null (never expires). |
__self__ | Reference to itself. |
Example Object
{
"hookId": "2a96cc80-97da-11e7-a2e5-6fa1bae9fd46",
"tenant": "228780",
"callbackUrl": "http://bf067e05.ngrok.io/callback",
"createdBy": "*********",
"event": "dm.version.added",
"createdDate": "2017-09-12T16:48:13.128+0000",
"system": "data",
"creatorType": "O2User",
"scope": {
"folder": "urn:adsk.wipprod:fs.folder:co.WGiFD3Y-T4GdynbaM5ojeQ"
},
"urn": "urn:adsk.webhooks:events.hook:2a96cc80-97da-11e7-a2e5-6fa1bae9fd46",
"status": "active",
"autoReactivateHook": false,
"hookExpiry": "2017-09-21T17:04:10.444Z",
"__self__": "/systems/data/events/dm.version.added/hooks/2a96cc80-97da-11e7-a2e5-6fa1bae9fd46"
}
Secret Token
As you expose your application endpoint to receive calls from the Webhooks service, you probably want that endpoint to only receive data from your configured webhooks. Your secret token enables you to validate that the call comes from the Webhooks service.
Tokens are used to sign the callback payload for webhooks when an event occurs. Each application or user can register a secure token using its own client id or user id that will be later used to sign the payload.
Schema
Attribute | Description |
---|---|
token | Alphanumeric token used to sign event callback’s payload. |
Example Object
{
"token":"eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0"
}