POST to your server when a job finishes. Webhooks are available on every plan.
Configuring
Two options, in order of precedence:- Per job: pass
webhookUrlin thePOST /v1/textorPOST /v1/audiobody. - Account default: set a default webhook URL in dashboard settings. Used for any job without its own
webhookUrl.
Payload
Sent forjob.completed and job.failed:
The webhook carries the raw stored result. To get a downloadable signed
outputUrl, fetch GET /v1/jobs/:id after receiving the event.Verifying signatures
Each account has a webhook secret (whsec_...), shown in dashboard settings. The signature is an HMAC-SHA256 of the string "{timestamp}.{body}": the timestamp header, a dot, and the raw request body.
Delivery and retries
- Your endpoint must respond with a 2xx status within 10 seconds.
- Failed deliveries (timeout or non-2xx) are retried up to 5 times with exponential backoff, the first retry after ~15 seconds, then increasing.
- Deliveries can arrive out of order or more than once; make your handler idempotent on
job.id+event. - Webhook delivery never affects the job itself: the result is persisted and remains fetchable via
GET /v1/jobs/:ideven if every delivery fails.