AI VideoWebhooksIdempotencyAPI

Handle Duplicate Video Generation Webhooks Without Delivering Twice

Webhook retries, out-of-order events, and polling can report the same video job. Use a terminal state and a unique delivery record to process completion once.

Handle Duplicate Video Generation Webhooks Without Delivering Twice

Your poller can see a video finish before two copies of the completion webhook arrive. All three observations concern one job; they should not each start a download and send a notification. The HTTP 2xx acknowledges a handled or durably recorded event, not a video safely in your archive.

Why does a provider send the event again?

The first write may have committed even though the HTTP response never reached the sender. The fal webhook documentation explicitly asks receivers to tolerate repeats for the same request_id. If processing retried internally, gateway_request_id can refer to the last attempt; use the queue's request_id for job identity. Replicate's webhook documentation notes that terminal events can be retried and events may arrive out of order, while intermediate notifications are not retried. Those are provider-specific contracts.

The first delivery commits but its response is lost, so the repeated delivery finds the same record

Verify the source using the provider's documented method and match it to a known provider account and job. For fal, verify the signature against the raw body and check the timestamp as documented. Do not trust a media URL from an unverified payload. Nbility's native Seedance API uses polling and does not accept a callback address. Apply the same delivery rules to completion events emitted by your own poller rather than adding an unsupported request field.

Key the action, not just the delivery

To prevent a duplicate archive operation, use a key that describes the work: provider account, job ID, and save-video, for example. If a job yields multiple independent artifacts, include the artifact ID. A refreshed URL is still the same artifact. An identical prompt, on the other hand, can legitimately produce several jobs.

Send poll and webhook results through the same state update. Write the terminal state and the delivery record in one transaction:

Receive a verified terminal result
  Lock the existing local job record
  Already terminal: never regress; flag a conflicting terminal result
  First confirmed success: set state and insert a unique save-video to-do
  First confirmed failure or cancellation: set state without a download to-do
Commit before acknowledging; a worker downloads and validates the file

Polling and callbacks share one terminal-state check, and only the first success creates work

The atomic write matters: otherwise a crash can leave a successful job with no download ever scheduled. If terminal reports conflict, query the provider for the authoritative result; do not overwrite the saved outcome just because another message arrived later.

Notify only after you can deliver the file

Create a “ready to download” notification only once the worker has fetched, validated, and saved the video. Use a stable object-storage key and any idempotency key the destination supports. If it offers neither idempotency nor a way to look up delivery, mark a send with an unknown outcome for reconciliation. A local sent flag cannot guarantee one message in an external service. See recovering n8n runs that already took an external action for further examples.

Download and validation precede archiving and notification; an unknown delivery remains visible for reconciliation

Before launch, exercise duplicate success, a poll and a callback reporting success together, and a late “running” event after completion. Expect one archive task. Then simulate losing the notification receipt after storing the file: expect a searchable or unresolved delivery record, not a second generation. The provider docs were checked on November 20, 2026. We exercised the deduplication rules with synthetic events, but did not receive live callbacks or verify production delivery timing.

Related posts

Extend an Existing Shot With Seedance 2.5
Seedance 2.5AI VideoVideo Editing

Extend an Existing Shot With Seedance 2.5

Use Seedance 2.5 extend mode with a reference video and adaptive framing, then check motion, sound, and overlap before cutting the new footage in.

When to Use the MiniMax H3 Prompt Optimizer
MiniMax H3AI VideoPrompt Engineering

When to Use the MiniMax H3 Prompt Optimizer

MiniMax H3 prompt optimization adds a rewrite before generation. Compare two clips against the same shot brief before enabling it for approved prompts.

Run your Agent workflow through Nbility

Get an API key and connect OpenAI-compatible models and developer tools from one place.

Get an API key