webhooks/v1/systems/{system}/events/{event}/hooks
Retrieves a paginated list of webhooks for the specified event. The returned list contains a subset of webhooks accessible to the provided access token within the specified region.
If the pageState query string parameter is not provided, the first page of results is returned. Use the next value from the previous response to fetch subsequent pages.
Resource Information
| Method and URI | GET https://developer.api.autodesk.com/webhooks/v1/systems/{system}/events/{event}/hooks |
| Authentication Context | User context optional |
| Required OAuth Scopes | data:read |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is a two-legged access token obtained via a Client Credentials Grant flow, or a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.
The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context. |
| region string | The geographical location (region) of the server the request must be executed on. This also corresponds to the region where Webhook data is stored. It is also the location of the server that will make requests to your callback URL. Possible values:
Note: You can specify the region using three methods: the |
| x-ads-region string | The geographical location (region) of the server the request must be executed on. This also corresponds to the region where Webhook data is stored. It is also the location of the server that will make requests to your callback URL. Possible values:
Note: You can specify the region using three methods: the |
Request
URI Parameters
| system string | The ID of the system the webhook applies to. For example data for Data Management. See Supported Events for a full list of supported systems and their IDs. |
| event string | The event type the webhook subscribes to. See Supported Events for a full list of events. |
Request
Query String Parameters
| region enum:string | The geographical location (region) of the server the request must be executed on. This also corresponds to the region where Webhook data is stored. It is also the location of the server that will make request to your callback URL. Possible values:
Note: You can specify the region using three methods: the |
| scopeName string | The scope name used to create the hook. Filters retrieved webhooks by this value. For example: folder. |
| scopeValue string | The scope value used to create the hook. Further filters retrieved webhooks by this value. For example, a folder URN (urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw) when scopeName is folder, or a Model Derivative workflow ID when scopeName is workflow. You must specify scopeName when using scopeValue; otherwise scopeValue is ignored. |
| pageState string | A Base64 encoded string used to fetch the next page of the list of webhooks. If you do not provide this parameter, the first page of results is returned. Use the next value from the previous response to fetch subsequent pages. |
| status enum:string | The current state used to filter retrieved webhooks. Possible values are
Filtering by |
Response
HTTP Status Code Summary
| 200 OK | A list of webhooks was returned successfully. |
| 204 No Content | No webhooks exist. |
| 400 Bad Request | The request could not be processed due to invalid or malformed data. Check the request parameters, body format, and required fields before retrying. |
| 401 Unauthorized | The supplied authorization header was invalid or the token scope was not acceptable. Verify your authentication credentials and try again. |
| 403 Forbidden | The request was valid but lacked the necessary permissions. Verify your credentials and permissions before sending the request again. |
| 404 Not Found | The requested resource could not be found on the server. Review the request and try again. |
| 500 Internal Server Error | An unexpected error occurred on the server. Please try again later. |
Response
Body Structure (200)
| links object | Contains an object with the address of the next page of the list of webhooks. |
| next string | Base64 encoded string to retrieve the next page of the list of webhooks. |
| data array: object | An array of objects, where each object represents a webhook. |
| hookId string | The ID that uniquely identifies the webhook. |
| tenant string | The ID of the tenant from which the event originates. |
| callbackUrl string | The URL to send notifications to when the event is triggered. |
| createdBy string | The ID of the entity that created the webhook. It can be one of the following:
|
| event string | The event type the webhook subscribes to. See Supported Events for a full list of events and wildcard patterns. |
| createdDate string | The date and time when the webhook was created, formatted as an ISO 8601 date/time string. |
| lastUpdatedDate string | The date and time when the webhook was last modified, formatted as an ISO 8601 date/time string. |
| system string | The ID of the system the webhook applies to. For example data for Data Management. See Supported Events for a full list of systems. |
| creatorType string | Indicates what type of an entity created the webhooks. Possible values:
|
| status enum:string | Indicates the current state of the webhook. Possible values are
See Event Delivery Guarantees for more information on how the system deactivates webhooks and subsequently reactivates them. |
| autoReactivateHook boolean | true: Automatically reactivate the webhook if it becomes inactive.
See Event Delivery Guarantees for more information on how the webhooks service handles reactivation. |
| hookExpiry string | The date and time when the webhook will expire, formatted as an ISO 8601 date/time string. A missing or null value indicates that the webhook will never expire.
|
| hookAttribute object | Contains a JSON object for storing user-defined custom information. The maximum size of this object is less than 1KB. |
| * object | Contains a user-defined JSON object for storing custom information. The maximum size of this object is less than 1KB. |
| scope object | Specifies the extent to which the event is monitored. For example, if the scope is set to folder, the webhooks service will generate notifications for the specified event occurring in that folder and any subfolders or contained items. |
| folder string | The URN of the folder the scope is set to. Present only for Data Management events.
See Creating a Webhook and Listening to Data Management Events for more information. |
| workflow string | The ID of a Model Derivative workflow the scope is set to. Present only for Model Derivative events.
See Creating a Webhook and Listening to Model Derivative Events for more information. |
| hubId string | The ID of the hub that contains the entity monitored by this webhook. This field is returned only if it was specified during the webhook’s creation.
For BIM 360, a Data Management Hub ID corresponds to an Account ID. For Forma, a Data Management Hub ID corresponds to a Forma Hub ID. To convert either to a Data Management Hub ID, prefix the ID with |
| projectId string | The ID of the project that contains the entity monitored by this webhook. This field is returned only if it was specified during the webhook’s creation.
BIM 360 and Forma project IDs are different from Data Management project IDs. To convert BIM 360 or Forma Project IDs to Data Management Project IDs, prefix them with |
| token string | A secret token that is used to generate a hash signature, which is passed along with notification requests to the callback URL.
See the Secret Token section in API Basics for more information. |
| urn string | The URN of the webhook. |
| __self__ string | A link to itself. |
Response
Body Structure (204)
Response for 204 has no body.
Example
This example demonstrates how to retrieve a specific page of a list of webhooks for the dm.version.added event . The page is specified using the pageState query parameter.
Request
curl -v 'https://developer.api.autodesk.com/webhooks/v1/systems/data/events/dm.version.added/hooks?scopeName=folder&scopeValue=urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw&pageState=BNNBEACAtgALYWRzay53aXBkZXYNZnMuZmlsZS5hZGRlZAZmb2xkZXIydXJuOmFkc2sud2lwcWE6ZnMuZm9sZGVyOmNvLlRSM253QUtoVFNDQ0x0azY0VE52Q2cydXJuOmFkc2sud2lwcWE6ZnMuZm9sZGVyOmNvLlRSM253QUtoVFNDQ0x0azY0VE52Q2ctaHR0cDovL2FwaS53ZWJob29raW5ib3guY29tL2kvM0l6eGlLZndmL2luL3gy8H____3wf____Twpc5_2RqlBtCsLMPJlT9kABA=='\
-H 'Authorization: Bearer bNU4P0trbQKNSzxWksLPTzSbbmUz'
Response
HTTP/1.1 200
Content-Type: application/json
Date: Fri, 14 Sep 2017 17:14:09 GMT
Content-Length: 662
Connection: keep-alive
{
"links": {
"next": "/systems/data/events/dm.version.added/hooks?pageState=AMMAEACAtgALYWRzay53aXBkZXYNZnMuZmlsZS5hZGRlZAZmb2xkZXIydXJuOmFkc2sud2lwcWE6ZnMuZm9sZGVyOmNvLlRSM253QUtoVFNDQ0x0azY0VE52Q2cydXJuOmFkc2sud2lwcWE6ZnMuZm9sZGVyOmNvLlRSM253QUtoVFNDQ0x0azY0VE52Q2ctaHR0cDovL2FwaS53ZWJob29raW5ib3guY29tL2kvM0l6eGlLZndmL2luL3gy8H____3wf____Twpc5_2RqlBtCsLMPJlT9kABA=="
},
"data": [{
"hookId" : "0f60f6a0-996c-11e7-abf3-51d68cff984c",
"tenant" : "urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw",
"callbackUrl" : "http://bf067e05.ngrok.io/callback",
"createdBy" : "*********",
"event" : "dm.version.added",
"createdDate" : "2017-09-14T17:04:10.444+0000",
"lastUpdatedDate" : "2020-09-14T17:04:10.444+0000",
"system" : "data",
"creatorType": "Application",
"status" : "active",
"autoReactivateHook": false,
"scope" : {
"folder" : "urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw"
},
"urn" : "urn:adsk.webhooks:events.hook:0f60f6a0-996c-11e7-abf3-51d68cff984c",
"__self__" : "/systems/data/events/dm.version.added/hooks/0f60f6a0-996c-11e7-abf3-51d68cff984c"
}]
}