Webhooks for Video Rendering: Reliable Completion Workflows

Video rendering is asynchronous, so your application needs a dependable way to learn when a task finishes. Polling works, but completion webhooks reduce delay and unnecessary requests when many renders are active.

Register the webhook when rendering starts

Pass webhook_url to a render-start endpoint, such as POST /api/v1/video/:taskId/render or POST /api/v1/preview/:tempId/render. Task creation alone does not start rendering and therefore does not accept a public completion webhook.

Use an absolute HTTPS URL that your production service can receive. Do not use a development address or a URL behind interactive authentication.

Respond quickly

A webhook handler should validate the request shape, locate the local job, record the event, and return promptly. Move file downloads, media inspection, publishing, and customer notifications to a background queue.

Slow synchronous handlers create ambiguous failures: the sender may time out even though your database update succeeded.

Make processing repeat-safe

Networks retry and events can arrive more than once. Use the remote task ID and terminal status as an idempotency key. Updating a job to the same completed state should be harmless, and a duplicate event should not publish twice or send repeated customer notifications.

A practical transaction can:

1. Lock or select the local job by remote task ID.
2. Ignore the event if the same terminal state was already processed.
3. Store the new status and result URL.
4. Insert one outbox record for downstream work.
5. Commit, then let a worker process the outbox.

Confirm before irreversible actions

A completion event is a signal. Before charging another system, deleting source assets, or publishing publicly, retrieve the latest task state from the authenticated API. This also repairs situations where events arrive out of order.

Keep polling as a fallback

Webhooks can be delayed by DNS failures, deployment windows, or receiving-service outages. Periodically reconcile non-terminal jobs that are older than the normal render window. Back off polling intervals and stop after a defined operational deadline.

Current security boundary

The current project does not yet expose a webhook signature, retry queue, or delivery log. Treat the webhook URL as a secret capability, use an unguessable path, restrict accepted fields, and confirm the task through the authenticated API before high-impact actions. Do not interpret unsigned payload fields as authorization.

Observe the whole path

Record event receipt time, remote task ID, previous and next status, processing result, and a correlation ID. Metrics should reveal webhook latency, duplicate rate, handler failures, and jobs repaired by reconciliation polling.

This makes “the video never arrived” a diagnosable incident instead of a manual search across unrelated logs.

See the API reference for the current render endpoints and webhook limitations.