Request

Response

    List All Webhooks for a System
    GET

    webhooks/v1/systems/{system}/hooks

    Retrieves a paginated list of webhooks for the specified system. 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}/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:
    • US - (Default) Data center dedicated to serve the United States region.
    • EMEA - Data center dedicated to serve the European Union, Middle East, and Africa regions.
    • AUS - Data center dedicated to serve the Australia region.
    • CAN - Data center dedicated to serve the Canada region.
    • DEU - Data center dedicated to serve the Germany region.
    • IND - Data center dedicated to serve the India region.
    • JPN - Data center dedicated to serve the Japan region.
    • GBR - Data center dedicated to serve the United Kingdom region.

    Note: You can specify the region using three methods: the region header, the x-ads-region header, and the region query parameter. The region header takes precedence over the x-ads-region header, and the x-ads-region header takes precedence over the region query parameter.

    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:
    • US - (Default) Data center dedicated to serve the United States region.
    • EMEA - Data center dedicated to serve the European Union, Middle East, and Africa regions.
    • AUS - Data center dedicated to serve the Australia region.
    • CAN - Data center dedicated to serve the Canada region.
    • DEU - Data center dedicated to serve the Germany region.
    • IND - Data center dedicated to serve the India region.
    • JPN - Data center dedicated to serve the Japan region.
    • GBR - Data center dedicated to serve the United Kingdom region.

    Note: You can specify the region using three methods: the region header, the x-ads-region header, and the region query parameter. The region header takes precedence over the x-ads-region header, and the x-ads-region header takes precedence over the region query parameter.

    * Required

    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.

    Request

    Query String Parameters

    status
    enum:string
    The current state used to filter retrieved webhooks. Possible values are
    • active - Successfully delivered most recent event notifications.
    • inactive - Failed to deliver most recent event notification and has been deactivated.

    Filtering by reactivated is not currently supported; use the status field of each returned webhook to identify webhooks in that state. If this parameter is not specified, the filter is not applied. See Event Delivery Guarantees for more information on how the state of a webhook changes.

    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.
    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:
    • US - (Default) Data center dedicated to serve the United States region.
    • EMEA - Data center dedicated to serve the European Union, Middle East, and Africa regions.
    • AUS - Data center dedicated to serve the Australia region.
    • CAN - Data center dedicated to serve the Canada region.
    • DEU - Data center dedicated to serve the Germany region.
    • IND - Data center dedicated to serve the India region.
    • JPN - Data center dedicated to serve the Japan region.
    • GBR - Data center dedicated to serve the United Kingdom region.

    Note: You can specify the region using three methods: the region header, the x-ads-region header, and the region query parameter. The region header takes precedence over the x-ads-region header, and the x-ads-region header takes precedence over the region query parameter.

    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)

    Expand all
    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:
    • Client ID of an app: If created using a Client Credentials flow (two-legged OAuth).
    • User ID of a user: If created using an Authorization Code flow (three-legged OAuth).
    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:
    • O2User - Created by a user through an Authorization Code flow (three-legged OAuth).
    • Application - Created by an application using a Client Credentials flow (two-legged OAuth).
    status
    enum:string
    Indicates the current state of the webhook. Possible values are
    • active - Successfully delivered most recent event notifications.
    • inactive - Failed to deliver most recent event notification and has been deactivated.
    • reactivated - Previously inactive webhook that has been reactivated. No events have occurred since reactivation.

    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.

    false: (Default) Do not 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.

    hookExpiry is returned only if it was specified when the webhook was created.

    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 b. For example, a BIM 360 Account ID or Forma Hub ID of c8b0c73d-3ae9 translates to a Data Management Hub ID of b.c8b0c73d-3ae9.

    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 b. For example, a Project ID of c8b0c73d-3ae9 becomes b.c8b0c73d-3ae9.

    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 system data. The page is specified using the pageState query parameter.

    Request

    curl -v 'https://developer.api.autodesk.com/webhooks/v1/systems/data/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": "/systems/data/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