Webhooks
Webhooks
Get a signed POST when a staff member finishes a task, a job completes, a video is ready or credits run low, instead of polling.
A webhook endpoint is an https URL on your server that Dhanu POSTs to when something you subscribed to happens. Register one in Developers → Webhooks, pick the events, and copy the signing secret, it is shown once.
The envelope
Every delivery is one JSON object:
{
"id": "0b2f…",
"type": "task.completed",
"createdAt": "2026-09-17T10:16:40.000Z",
"workspaceId": "7a1c…",
"data": { "task": { "id": "…", "title": "Stand-up minutes" }, "message": { "…": "…" } }
}id is unique per event and identical across every endpoint and every retry of
that event, use it to de-duplicate. data is described per event on the
events page.
Three headers ride along:
| Header | Meaning |
|---|---|
Dhanu-Signature | t=<unix seconds>,v1=<hex>, verify it before doing anything |
Dhanu-Event | The event type, so you can route without parsing the body |
Dhanu-Delivery | The delivery id, unique per attempt; quote it in support |
Respond fast, then work
Return any 2xx within 10 seconds. Anything else, a timeout, a 5xx, a
redirect, counts as a failure. Do the real work after you have responded, on a
queue of your own.
Retries
A failed delivery is retried on a growing schedule: 1 minute, 5 minutes, 30
minutes, 2 hours, 6 hours, 12 hours, then daily, for roughly three days in
total. Because the same event can arrive more than once, handlers must be
idempotent, key them on the envelope id.
An endpoint that fails 30 deliveries in a row is disabled and shown as such in the console; fix it and switch it back on. Every attempt, its status code and the first 500 characters of your response are kept in the delivery log, where you can also resend any delivery and send a test event.
Rotating the secret
Rotate from the console at any time. The new secret is shown once; the old one
keeps verifying for 24 hours, and during that window Dhanu-Signature
carries two v1= values, one per secret, so a verifier that knows either passes.
Security
- Only https URLs, and never one that resolves to a private or loopback address.
- Treat the body as untrusted until the signature is verified.
- The signing secret never leaves your server. If it leaks, rotate it.