Request

Response

    Regionalization and Data Residency

    Autodesk offers its cloud services in a number of Autodesk Regions. An Autodesk Region is a country in which Autodesk stores and processes product data for the customers assigned to it, so the data behind a project in one region is not the same data, or in the same place, as the data behind a project in another.

    The Webhooks API carries that regional context. A webhook is created, stored, and delivered within one region, and a request that does not name the right region does not reach the right data. This topic explains how to work out which region applies to your workflow, how to specify it, and what happens when it is missing or wrong.

    How Regionalization Works with Webhooks

    The region is not something you choose for a webhook. It follows from the data you are subscribing to:

    1. An Autodesk resource exists in a region. The folder, project, or other resource your webhook watches belongs to an Autodesk product, and that product holds it in one Autodesk Region.
    2. You call Webhooks in that region. Each request you make specifies a region. The Webhooks service then acts on the webhooks that belong to that region.
    3. The webhook is stored in that region. The region you create a webhook in is where its subscription data is stored.
    4. The callback comes from that region. The server that sends the request to your callback URL is located in the region of the webhook.

    The consequence is that a webhook is only visible to requests made against its own region. If you create a webhook in one region and then list, update, or delete webhooks in another, the webhook you are looking for is not part of that result.

    Determine the Correct Region

    The Autodesk product that owns the data determines the region. The Webhooks API does not decide it for you, and it cannot be inferred from your app or your access token.

    • Start from the resource. Establish which Autodesk Region holds the hub, project, or folder your webhook watches. Product data for a hub is stored and processed in the region that contains that hub, so the answer is a property of the data, not of the subscription.
    • Use the product’s own documentation. The way you look up the region of a resource, and the regions a product is offered in, are defined by that product. See the documentation for the Autodesk service whose events you subscribe to, and the Creating a Webhook tutorial for it in the How-to Guide.
    • Match, do not guess. Use the same region value for every Webhooks request that touches a given webhook, from creation onwards.

    Specify the Region

    You use the same base URL, https://developer.api.autodesk.com, for every region. The region travels with the request.

    There are three ways to specify it, and they take precedence in this order:

    MechanismTypePrecedence
    region Header Highest. Overrides both of the following.
    x-ads-region Header Overrides the query string parameter.
    region Query Lowest.

    If you do not specify a region by any of these means, the request is executed against US.

    Supported Values

    ValueData center
    US (Default) Dedicated to serve the United States region.
    EMEA Dedicated to serve the European Union, Middle East, and Africa regions. See GDPR Compliance for more information on data residency and compliance requirements for this region.
    AUS Dedicated to serve the Australia region.
    CAN Dedicated to serve the Canada region.
    DEU Dedicated to serve the Germany region.
    IND Dedicated to serve the India region.
    JPN Dedicated to serve the Japan region.
    GBR Dedicated to serve the United Kingdom region.

    The reference page for each operation lists the region parameters that operation accepts. See the REST API Reference.

    Example

    To create a webhook against the Germany region, send the region in the region header:

    curl -X 'POST'
         -v 'https://developer.api.autodesk.com/webhooks/v1/systems/data/events/dm.version.added/hooks'
         -H 'Content-Type: application/json'
         -H 'authorization: Bearer <ACCESS_TOKEN>'
         -H 'region: DEU'
         -d '{
                "callbackUrl": "https://myapp.example.com/callback",
                "scope": {
                     "folder": "<FOLDER_URN>"
                }
          }'
    
    Show More

    Operations and Regional Context

    Regional context applies to the whole life of a webhook, not only to creating it.

    OperationHow the region applies
    Create Determines the region the webhook is created and stored in, and the region the callback is sent from.
    Retrieve and list Returns only the webhooks belonging to the region of the request.
    Update Applies only to a webhook in the region of the request.
    Delete Applies only to a webhook in the region of the request.

    Send the same region value on every one of these calls for a given webhook.

    Common Problems

    The region is missing. A request without a region is executed against US. If your data is in another region, a create request registers a webhook in the wrong region, and a list, update, or delete request does not act on the webhook you expect.

    The region is wrong. The Webhooks service acts on the region you named, not the one your data is in. A request that names the wrong region behaves the same way as a missing one: it operates on a region where your webhook does not exist.

    You are operating on a webhook in a different region. When you send a request against a region that does not hold the webhook, the webhook cannot be found. Verify that the region value matches the value you used when you created the webhook, and that it matches the region of the resource in the scope.

    Next Steps

    • Authenticate your requests. See Authentication for Webhooks.
    • Create a webhook in your region. Follow the tutorial for your Autodesk service in the How-to Guide, which states the requirements specific to that service.
    • Check which webhooks exist in a region. See Retrieve a List of Webhooks.
    • Look up the parameters for an operation. See the REST API Reference.
    • Find your product’s regional guidance. The regions a product is offered in, and how to determine the region of a resource, are documented by that product.