Webhook delivery is retried when your endpoint does not return a successful response. A retry can arrive after your receiver already stored the first attempt but its acknowledgment was lost. Design repeated receipt as an expected condition.
Use the stable delivery ID
Read Waiver-Delivery-Id. It stays the same across attempts for one delivery. Store it with a unique constraint in your durable inbox or queue. If an already accepted delivery arrives again, acknowledge it without creating a second business action.
Do not deduplicate by arrival time, request ID or the whole raw body. Those choices make it harder to distinguish a transport retry from an intentional new event.
Make acceptance atomic
Persist the delivery identifier and the work to perform in the same transaction where possible. A sequence that first marks an ID as processed and only later enqueues the job can lose work between those steps.
Keep separate states for accepted, processing and completed work in your own system. “Seen” is not the same as “the destination was updated.” A worker crash should leave a job that can safely resume.
Protect the downstream operation
Upserting a record by waiver ID is often easier to repeat safely than appending a new row on every attempt. If the destination action is a message or another side effect, give that business action its own deduplication rule.
Manual replay creates a new delivery ID. Your transport-level deduplication will correctly accept it, but the underlying historical event may refer to something you already processed. Keep event identity and delivery identity separate where your business logic needs that distinction.
Handle ordering deliberately
Do not rely on signed, flagged and other events arriving in a fixed order. Retrieve current state when the operation requires the latest record, and preserve historical event information when your application needs an audit trail.
Test a duplicate arriving during processing, a duplicate after completion and a replay with a new delivery ID. Pair those tests with signature verification, then use replay only after understanding why the original delivery failed.