API Basics
Webhooks APIs allow applications to subscribe to APS events, and receive notifications when they occur. When an event is triggered, the Webhooks API sends a notification to a callback URL. Callback URL is set when a webhook is created.
There are four key elements to a webhook:
- The target service of interest.
- The events from the target service to subscribe. Please check Supported Events section for additional information.
- The callback URL i.e. URL where the Webhooks service will notify when the events occur.
- The Scope i.e. the domain of the data for which this webhook was created.
Webhook
A webhook can be created by simply making a POST
request to webhooks/v1/systems/:system/events/:event/hooks
.
You can find additional details in the Reference Guide.
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 bNU4P0trbQKNSzxWksLPTzSbbmUz'
-d '{
"callbackUrl": "http://bf067e05.ngrok.io/callback",
"scope": {
"folder": "urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw"
}
}'
Callback
When the event occurs, the webhooks service sends a payload to the callback URL as an HTTP POST request. The webhook service expects a 2xx response to the HTTP POST request. The response must be received within 6 seconds. A non-2xx response or no response within 6 seconds is considered an error.
When there is no error from the registered callback URL, the Webhooks service guarantees at least once delivery. In the event of an error, the call will be retried four times, with the final attempt being at least 48 hours after the initial attempt. If last retry attempt fails, the webhook will be disabled and it will need to be re-enabled using PATCH systems/:system/events/:event/hooks/:hook_id.
Secret Token
Webhooks API also supports setting a secret token to prevent callback spoofing. When your secret token is set, Webhooks Service uses it to create a hash signature for each payload. This hash signature is passed along with each request, as the header x-adsk-signature
. In order to validate that the request came from Autodesk Webhooks service, subscribers should compute a hash using their token, and ensure that the hash from Webhooks Service matches. Webhooks uses an HMAC hexdigest to compute the hash.
Note: Tokens can be set on a per user (user context) or per application basis.
Getting Started
Take a look at our How-to Guide to see how to add your first webhook in Webhooks API.