Events
batch.progress is off by default because a large batch emits several. Add it to events if you want to track a batch as it runs; it fires at most once per 10% and never for batches under 5 videos. It is never sent at 100% — batch.completed covers that.
Register a webhook
Response
Webhook payload
Every event arrives in the same envelope:data. The four envelope keys are:
timestamp reflects the job’s completion time, so events stay correctly ordered even when a batch fan-in dispatches them later.
Headers
X-FastDrop-Event-Id lets you dedupe before parsing the body.
Idempotency
Delivery is at-least-once. A retry, a manual replay, or a network timeout where your server actually succeeded can all produce a repeat. Theid is identical every time:
id, not on job_id — a job legitimately produces more than one event.
Verifying signatures
Every webhook is signed with your secret using HMAC-SHA256. Always verify before acting.Verify against the raw request body. Re-serialising the parsed JSON will not reproduce our bytes, and the signature will not match. In Express use
express.raw(); in FastAPI use await request.body().A complete receiver
Retry policy
Non-2xx or a timeout triggers retries with exponential backoff:
After 3 failed attempts the delivery is marked
failed. It is not lost — inspect and replay it below.
Delivery history
Every delivery is recorded with the response your server gave.Response
webhook_id, job_id, event, status, before, limit. Paginate by passing next_cursor as before.
To see exactly what we sent — useful when your parser and our payload disagree — fetch one delivery:
payload field containing the verbatim body.
Replaying a delivery
Fixed your endpoint, or lost an event downstream? Replay it:id are unchanged, so a handler that dedupes on id is safe. Replaying costs no credits — you never need to re-run a job to recover an event.
A delivery still queued for another automatic attempt returns 409 delivery_in_flight; wait for that attempt to resolve.
Rotating a secret
secret, shown once. The old secret stops working immediately — if your handler rejects bad signatures, deploy the new secret before rotating, or expect a few retried deliveries while you catch up.
Testing
test event in the same shape your endpoint receives for real events, including the signature. If your handler passes this, it will pass a real job.completed.
Per-request webhooks
For a one-off callback without registering an endpoint, passwebhook_url on the submission:
- The body is flat —
job_id,status,results,completed_atat the top level, no envelope. This shape predates the envelope and is kept for compatibility. - It is unsigned unless you pass
webhook_secret. Do pass one; without it you cannot prove the request came from us.
Managing endpoints
Getting your results
How webhooks compare to long-poll, and when to use which.