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:
- 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.
- 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.
- The webhook is stored in that region. The region you create a webhook in is where its subscription data is stored.
- 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:
| Mechanism | Type | Precedence |
|---|---|---|
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
| Value | Data 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>"
}
}'
Operations and Regional Context
Regional context applies to the whole life of a webhook, not only to creating it.
| Operation | How 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.