Async video generation in production: a webhook checklist

Video generation takes from tens of seconds to several minutes, so it should never block a web request. Treat each generation as a job: submit, store the task id, and react when it completes.

Submit with a callback URL and an idempotency key

curl https://apimany.com/v1/videos/generations \
  -H "Authorization: Bearer $APIMANY_API_KEY" \
  -H "Idempotency-Key: order-1842-shot-3" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5", "prompt": "...", "duration": 8, "resolution": "720p", "callback_url": "https://your-app.com/hooks/apimany"}'

• Store the returned id with your own record before doing anything else.
• Use an Idempotency-Key derived from your own ids so a retried submit never creates a second job.

Verify the webhook

Each delivery carries X-Apimany-Timestamp and X-Apimany-Signature, an HMAC-SHA256 of "timestamp.body" with your webhook secret. Reject anything that does not verify or is older than a few minutes, and respond 2xx quickly — do heavy work in a queue.

Poll as a safety net

Webhooks can be blocked by firewalls or lost during your own deploys. A periodic job that polls GET /v1/tasks/{id} for anything still pending after a few minutes closes the gap.

Copy results to your storage

Result links are signed and stay valid for 30 days. Copy files you want to keep to your own bucket when the job completes, not when a user first asks for them.

Budget for the reserve

Each job reserves its maximum cost when submitted and settles when it finishes; failures release the reserve. Keep enough balance for the jobs you run in parallel, or enable auto top-up.