Webhooks (callbacks)

Instead of polling, pass a callbackUrl when you create a task. When the task reaches a terminal state we POST the result to that URL. The callbackUrl must be https and publicly reachable.

{
  "taskId": "a1b2c3d4e5f6g7h8",
  "status": "success",
  "resultUrls": ["https://you.bot/api/file?t=…"]
}

• Respond 2xx quickly to acknowledge; do heavy work after acknowledging.
• We retry failed deliveries with backoff for a limited window.
• Match the taskId against your own records before acting; you can still poll as a fallback.
• Signature: create a webhook signing key in Dashboard → Settings, and every delivery then carries `X-Webhook-Signature: sha256=<hex>` — an HMAC-SHA256 of the exact request body with that key. Until a key exists the header is absent, so verify only once you have created one.