Skip to main content
Webhooks notify your app when an asynchronous task completes, fails or times out. Configure them in Dashboard → API → Webhooks, through the Management API, or through TokenLab MCP’s full profile. They share the same workspace endpoints and delivery history.

Which credential to use

Create a Management Token at Dashboard → API → Management Tokens. Tokens are workspace scoped: choose the same workspace as the API key submitting tasks. A token cannot read or modify another workspace’s endpoints. API keys and signing secrets are rejected by the Management API. Dashboard configuration uses your signed-in workspace admin session. Store mt-… and whsec_… on your backend. Do not embed them in browser code, prompts, repository files or URLs. Management Tokens also authorize other workspace management operations; they are not webhook-only credentials.

Configure an endpoint

The 201 response includes id and a one-time secret beginning with whsec_. Store the secret before leaving this step. List/get/update responses never expose it. Up to 10 endpoints can be configured per workspace. URLs must use public HTTPS and cannot contain credentials, query strings or fragments. Redirects are not followed. Pause with PATCH {"is_active":false}; resume with PATCH {"is_active":true}. Resuming resets the consecutive failure count. Rotation returns a new secret once; configure it on your receiver immediately. Requests already in flight may still carry the previous signature, so briefly accept both secrets during rotation. Rotation is not reversible.

Events and payloads

Subscriptions cover future terminal async task events; synchronous results and historical tasks are not replayed. Receive all workspace tasks for the selected event types and match data.taskId to the ID returned when you created the task. Callback fields use camelCase; management response fields use snake_case.
Fields depend on the task and can be absent. Use GET /v1/tasks/{id} with the original workspace’s sk-… key for the authoritative result and billing status. An event’s retryable describes the generation failure; it is not an instruction to poll a terminal task indefinitely or automatically submit a new billable task.

Verify before processing

Each POST includes X-Webhook-ID, X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature (sha256=<hex>). Compute HMAC-SHA256 over the exact timestamp string, a period, and the raw request body bytes, using the complete whsec_… secret. Do not parse and reserialize JSON before verification.
After verification, check the body id matches X-Webhook-ID, persist the event ID with your work item atomically, and return 2xx quickly. Process heavy work from your own queue. Deduplicate by event ID within the receiving endpoint: deliveries can repeat and ordering is not guaranteed. A five-minute timestamp tolerance limits replay age; ID deduplication prevents repeated processing within that window.

Retries and recovery

Each delivery cycle makes up to three attempts, waiting 1 second then 4 seconds. Each HTTP attempt has a 10-second timeout and a fresh timestamp/signature. Network failures, 429, and 5xx are retryable. Other 4xx, redirects and invalid network targets stop that cycle without retrying. Transient failures can trigger later event retries with the same delivery ID. Ten consecutive failed cycles automatically pause the endpoint. Use the test operation and delivery history to see outcome, http_status, attempts and delivered_at. A successful test API response (200) only means the attempt was recorded: check outcome == "delivered". Fix the receiver, resume the endpoint, then send another test. History contains delivery metadata, not payloads; manual replay of old events is not available. Keep task IDs and reconcile with task status if your receiver was paused or unavailable.

MCP configuration

Webhook management tools are available in the full profile. The management credential is separate from the inference key; catalog and webhook management can work without an inference key.
Tools: list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries. Never paste credentials into a tool argument. Grant management access only to trusted MCP clients.

Polling fallback

Webhooks do not remove status-query access or impose a new polling limit. If you poll, use the creation response’s poll_url, back off while pending, and stop on terminal states. Stop on 401, 403, 404, or error.retryable == false; retry transient 503 async_task_owner_unavailable with backoff. A missing or expired task returns 404 async_task_not_found. Repeatedly querying a missing task cannot recreate it. The Seedance compatibility API’s callback_url is a separate per-request callback contract. It can be set when creating that task; it does not use these workspace event payloads or HMAC headers.