Request

Response

    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 status field of a webhook to find out whether it is still delivering callbacks.
    • Obtain the hookId of a webhook so that you can update or delete it.

    Before You Begin

    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"
      }]
    
    }
    
    Show More

    What the Response Contains

    Each entry in data describes one webhook. The fields you are most likely to need are:

    FieldWhat 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.

    OperationReturns
    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"
      }]
    }
    
    Show More

    Step 3: Check the Status of a Webhook

    The status field of a webhook reports whether it is still delivering callbacks:

    ValueMeaning
    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.