Notify applications when assets become ready without duplicate side effects.
Publish state changes as events
A processing system can emit uploaded, ready, failed, or deleted events after committing the corresponding state. Give each event a unique ID, asset ID, event type, timestamp, and schema version. The receiver should be able to fetch the current asset state rather than treating an event payload as the only truth.
Verify and deduplicate
Sign webhook requests and verify the signature over the raw request body. The consumer records event IDs and handles repeat deliveries idempotently. A fast acknowledgment followed by queued work keeps transient downstream slowness from causing unnecessary retries.
Expect disorder
Events can arrive late or out of order. Make handlers compare versions or retrieve current state before moving a record backward. Provide a replay or reconciliation path so a temporary endpoint outage does not leave an asset permanently stuck in processing.
A concrete acceptance test
Deliver ready twice, then deliver an older processing event. The consumer should acknowledge all three requests while the application keeps one ready asset state. Run this test with a realistic asset and record the observed state, output URL, and failure reason.
Implementation check
- Verify signatures against the raw body.
- Deduplicate by event ID before side effects.
- Reconcile state when events arrive out of order.
Related guides
Primary reference: Official documentation.