Retrieve a List of Webhooks
This walkthrough demonstrates how to retrieve the webhooks you have already created, and how to inspect individual webhooks.
Retrieve your webhooks when you need to:
- Check which subscriptions exist and where their callbacks are sent.
- Read the
statusfield of a webhook to find out whether it is still delivering callbacks. - Obtain the
hookIdof a webhook so that you can update or delete it.
Before You Begin
- Register an app on the APS portal, and enable the Webhooks API on it.
- Acquire a two-legged access token or a three-legged access token with the
data:readscope. - If your webhooks were created outside the default
USregion, note which region they were created in. You must send the request to list webhooks to the same region where they were created. See Regionalization and Data Residency.
Step 1: Retrieve Your Webhooks
Send a GET request to webhooks/v1/hooks. The response lists the webhooks that are accessible with your access token and were created in the region where you send the request.
Request
curl -v 'https://developer.api.autodesk.com/webhooks/v1/hooks?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
Connection: keep-alive
{
"links": {
"next": "/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,
"hookExpiry": "2017-09-21T17:04:10.444Z",
"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"
}, {
"hookId" : "1f63f6a4-106c-11e7-qrf9-72d68cff984d",
"tenant" : "urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw",
"callbackUrl" : "http://bf067e05.ngrok.io/callback",
"createdBy" : "*********",
"event" : "dm.version.copied",
"createdDate" : "2017-09-14T17:04:10.564+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:1f63f6a4-106c-11e7-qrf9-72d68cff984d",
"__self__" : "/systems/data/events/dm.version.copied/hooks/1f63f6a4-106c-11e7-qrf9-72d68cff984d"
}]
}
What the Response Contains
Each entry in data describes one webhook. The fields you are most likely to need are:
| Field | What it tells you |
|---|---|
hookId |
The ID of the webhook. Use it to retrieve, update, or delete the webhook. |
system |
The system the webhook belongs to, such as data. |
event |
The event the webhook subscribes to, such as dm.version.added. |
scope |
The data the webhook watches, as a scope name and value. |
callbackUrl |
The URL that callbacks are sent to. |
status |
Whether the webhook is currently delivering callbacks. See Step 3. |
__self__ |
The path of the webhook, which contains its system, event, and ID. |
Every field of a webhook is described in the Field Guide.
Read the Next Page of Results
The response is paginated. If more webhooks exist than fit on one page, the response contains a links.next value. Pass its pageState value back in the pageState query string parameter to retrieve the following page, and repeat until the response contains no next value. If you omit pageState, you receive the first page.
Step 2: Narrow the List
If you know which subscription you are looking for, you can ask for less than the full list.
| Operation | Returns |
|---|---|
| GET hooks | All webhooks available to your access token. |
| GET systems/:system/hooks | The webhooks for one system. |
| GET systems/:system/events/:event/hooks | The webhooks for one event in one system. |
| GET systems/:system/events/:event/hooks/:hook_id | The details of one webhook. |
GET systems/:system/events/:event/hooks also accepts the scopeName and scopeValue query string parameters, which filter the result by the scope the webhook was created with. You must specify scopeName when you use scopeValue.
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"
}]
}
Step 3: Check the Status of a Webhook
The status field of a webhook reports whether it is still delivering callbacks:
| Value | Meaning |
|---|---|
active |
The webhook delivered the most recent event notifications successfully. |
inactive |
The webhook failed to deliver the most recent event notification and has been deactivated. |
reactivated |
The webhook was previously inactive and has been reactivated. No events have occurred since. |
To list only the webhooks that are active or inactive, add the status query string parameter. For example, to find the webhooks that have stopped delivering callbacks:
curl -v 'https://developer.api.autodesk.com/webhooks/v1/hooks?status=inactive'\
-H 'Authorization: Bearer <ACCESS_TOKEN>'
If you omit status, no filter is applied. Filtering by reactivated is not currently supported, so use the status field of each returned webhook to identify webhooks in that state.
To re-enable an inactive webhook, use the Update a Webhook operation. For how a webhook becomes inactive and how automatic reactivation works, see Event Delivery Guarantees.