Creating a Webhook (Model Derivative)
This walkthrough demonstrates how to create a webhook that notifies your app when a Model Derivative translation job completes, so your app can act on the result instead of repeatedly polling for job status. The steps include selecting an event type, choosing a workflow ID to use as the webhook scope, preparing the callback, creating and verifying the webhook, testing the webhook, and verifying callback authenticity.
For more details about the Model Derivative API, see the Model Derivative documentation.
Before You Begin
- Register an app and select both the Webhooks API and the Model Derivative API.
- Acquire a two-legged access token with the
data:readanddata:writescopes, which are required for both the Model Derivative API and the Webhooks API. For choosing and acquiring an access token, see Authentication for Webhooks. - Have a design file that has already been uploaded to OSS. See Upload a File. You’ll need the base64 encoded value of the URN of this file to submit a translation job in Step 6.
Step 1: Select an Event Type
The Model Derivative service lets you monitor the following events, both in the derivative system.
| Event | Trigger |
|---|---|
extraction.finished |
When a job is completed. |
extraction.updated |
When the status of a job changes from pending to inprogress. |
You can also subscribe with a wildcard, such as extraction.*, to cover both events with one webhook. See Supported Events.
In this walkthrough, assume that you want to subscribe to extraction.finished, which sends a notification to the callback URL when the translation job completes.
Note that “completed” means the job reached an end state, not that it succeeded. The payload of extraction.finished carries the outcome in payload.Payload.status, and the documented examples include values such as success and failed. Check that field before treating a callback as a success. If you only want to hear about a subset of outcomes, see Callback Filtering.
Step 2: Choose a Workflow ID
Model Derivative webhooks are scoped differently from webhooks for most other Autodesk services. For a service such as Data Management, you typically scope a webhook to an existing resource, such as a folder URN. With Model Derivative, you scope the webhook to a workflow ID that you define yourself.
You choose the workflow ID when you create the webhook, and then use the same ID when submitting translation jobs. The Webhooks service sends a notification to your callback URL when an event associated with that workflow ID occurs. The relationship is:
webhook created with a workflow ID → translation job submitted with the same workflow ID → event associated with that workflow ID occurs → notification sent to your callback URL
Decide the value you will use as your workflow ID. This ID links the translation job you kick off in Step 6 to the webhook subscription you create in Step 4.
Choose a value that identifies something meaningful in your own system, so that when a callback arrives you know what it relates to. This walkthrough uses my-workflow-id.
You will use this same value twice: once in the scope of the webhook, and once in the translation job you want it to monitor. The workflow ID must be 36 characters or less and can only contain alphanumeric characters (A-Z, a-z, 0-9) and hyphens (-).
Step 3: Prepare the Callback
The Webhooks service delivers notifications by sending an HTTP POST request to the callback URL you register. The URL has to be reachable from the internet and has to acknowledge the request quickly.
See Configuring Your Server for what the callback has to do and how to expose a local server while developing. It also covers what to settle before production.
Step 4: Create the Webhook
Create the webhook before submitting the translation job. Webhooks can receive event notifications only after they are created, so if the translation job has already finished by the time the webhook is created, you will not receive an event notification for that job.
Create the webhook by calling POST systems/:system/events/:event/hooks.
Set callbackUrl to the callback URL you prepared in Step 3, and set scope to {"workflow": "<your workflow ID>"} using the value you chose in Step 2. The workflow scope is valid only for Model Derivative webhooks. The callback URL cannot be changed after the webhook is created, so use a URL you control rather than a temporary tunnel if this webhook is going to production.
Optional fields such as filter, hookAttribute, and hookExpiry are described in the Webhooks Field Guide. For the full request body, see Create a Webhook for an Event.
If your webhook is registered in a region other than the default US, you must explicitly specify that region when performing webhook operations. See Regionalization and Data Residency for the supported mechanisms and values.
Request
curl -X 'POST' \
-v 'https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks' \
-H 'Content-Type: application/json' \
-H 'authorization: Bearer <ACCESS_TOKEN>' \
-d '{
"callbackUrl": "https://myapp.example.com/callback",
"scope": {
"workflow": "my-workflow-id"
}
}'
A successful request returns 201 with an empty body and a Location header (or location if your connection uses HTTP/2):
HTTP/1.1 201
Location: https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks/0f60f6a0-996c-11e7-abf3-51d68cff984c
Content-Length: 0
Note the Location value (returned as location if your connection uses HTTP/2). Its final path segment is the hookId. You can use the hookId together with the system and event to retrieve, update, or delete the webhook.
If the request returns 401 or 403, check that your access token is valid and has the correct type and scopes. See Authentication for Webhooks.
If the request returns 400, check the request body and confirm that you are using workflow as the scope name. The workflow scope is valid only for Model Derivative webhooks.
If the request returns 409, a webhook with the same callback URL, scope, and event already exists. Retrieve your existing webhooks before creating another.
If the request returns 429, you have exceeded a rate limit. Wait before retrying the request. See Rate Limits and Quotas.
Step 5: Verify the Webhook
Confirm the webhook exists and is configured as you intended before you rely on it.
Request
curl -v 'https://developer.api.autodesk.com/webhooks/v1/hooks' \
-H 'authorization: Bearer <ACCESS_TOKEN>'
Response
The response lists your webhooks, abridged here to the entry for the one you just created:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"hookId": "0f60f6a0-996c-11e7-abf3-51d68cff984c",
"system": "derivative",
"event": "extraction.finished",
"createdBy": "*********",
"creatorType": "Application",
"createdDate": "2026-01-01T12:00:00.000+0000",
"status": "active",
"callbackUrl": "https://myapp.example.com/callback",
"scope": {
"workflow": "my-workflow-id"
},
"urn": "urn:adsk.webhooks:events.hook:0f60f6a0-996c-11e7-abf3-51d68cff984c",
"__self__": "/systems/derivative/events/extraction.finished/hooks/0f60f6a0-996c-11e7-abf3-51d68cff984c"
}
]
}
In the entry for your new webhook, check that:
statusisactive.systemisderivativeandeventisextraction.finished.scopeis{"workflow": "my-workflow-id"}, matching the value you will send in the job.callbackUrlis the URL you intended.
You can also navigate directly to the Location URL (or location if your connection uses HTTP/2) from Step 4 to read this one webhook. For more information about retrieving webhooks, see Retrieve a List of Webhooks. For reading each field, see the Webhooks Field Guide.
If the webhook does not appear in the response, verify that you are listing webhooks in the same region where the webhook was created. See Regionalization and Data Residency.
For more information about webhook status and diagnosing delivery problems, see Monitoring and Troubleshooting.
Step 6: Test the Webhook
Trigger the event by submitting a translation job that carries your workflow ID. Set misc.workflow to the same value you used in the scope of the webhook:
curl -X 'POST' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-H 'Content-Type: application/json' \
-H 'authorization: Bearer <ACCESS_TOKEN>' \
-d '{
"input": {
"urn": "<BASE64_ENCODED_URN_OF_YOUR_FILE>"
},
"output": {
"formats": [{
"type": "obj"
}]
},
"misc": {
"workflow": "my-workflow-id"
}
}'
See POST job in the Model Derivative documentation for the full request. It covers the available output formats and the scopes this operation requires.
When the job completes, the Webhooks service sends a POST request to your callback URL. The body looks like this, abridged:
{
"version": "1.0",
"resourceUrn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6d2htZHRlc3RzdGcvQ2FzZUlubmVyLmlwdA",
"hook": {
"hookId": "a228fb60-106b-11e8-9774-490cff0c6aae",
"system": "derivative",
"event": "extraction.finished",
"scope": {
"workflow": "my-workflow-id"
}
},
"payload": {
"TimeStamp": 1513134729128,
"URN": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6d2htZHRlc3RzdGcvQ2FzZUlubmVyLmlwdA",
"EventType": "EXTRACTION_FINISHED",
"Payload": {
"status": "success",
"scope": "7dca556c-e041-444a-91cf-cdea18a7699e",
"registerKey": []
}
}
}
To confirm success, check that hook.hookId matches the webhook you created and that hook.scope.workflow matches the workflow ID you sent in the job. Read payload.Payload.status to find out whether the translation succeeded. For the complete body and the headers that accompany it, see extraction.finished.
If the job completed but no callback arrived, confirm that the job’s misc.workflow value exactly matches the workflow value in the webhook’s scope, that the webhook existed and was active when the job completed, and that your callback URL is reachable from the internet and acknowledges the request promptly. See Configuring Your Server. For more information about diagnosing callback delivery problems, see Monitoring and Troubleshooting.
If deliveries keep failing, the webhook becomes inactive. Fix the callback issue, then reactivate the webhook. See Event Delivery Guarantees.
If the translation job itself does not behave as expected, see the Model Derivative documentation.
Step 7: Verify Callback Authenticity
Your callback URL is reachable by anyone, so verify that a callback genuinely came from the Webhooks service before acting on it.
The access token and the secret token serve different purposes:
- The access token authorizes the calls your app makes to the Webhooks and Model Derivative APIs.
- The secret token you set on your webhooks is used to sign each callback, so your app can verify that an incoming notification is genuine.
The access token is not sent with the callback.