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.

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.
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
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.
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.


