Deduplicate webhook deliveries
Use the Dosya event ID as a transactional idempotency key so automatic retries and manual redelivery cannot repeat downstream side effects safely.
Last reviewed
Use the event ID for business idempotency. Automatic retries reuse both IDs, but manual redelivery deliberately creates a new delivery ID while retaining the same event ID and exact payload.

Steps
- Verify
X-Dosya-Signatureover the raw body, then readX-Dosya-Event-Idand confirm it matches the body’s top-levelid. Treat an absent or conflicting value as malformed input. - Begin a database transaction and insert the event ID into a table with a uniqueness constraint. Store the event type, first delivery ID, receipt time, and processing state without exposing the payload in ordinary logs.
- If the insert conflicts, return a 2xx after confirming the existing record is committed. Do not reapply the downstream change merely because
X-Dosya-Delivery-Iddiffers. - If the insert succeeds, apply the state change and commit the idempotency record in the same transaction or atomic workflow. A crash between the side effect and its marker is the duplicate window this design closes.
- Retain each delivery ID in an attempt log for diagnostics. Automatic retry keeps the original delivery ID; Redeliver creates a fresh
whd_…value but copies the originalevt_…event ID. - Force one receiver failure, allow a retry, and then use Redeliver on that row. Verify that all requests are traceable while the business table changes exactly once for the shared event ID.
Dosya event IDs are generated once per emitted event. One event can fan out to multiple subscribed endpoints, so event-based deduplication also protects a receiver accidentally registered more than once.

Expected result
The first verified event commits one downstream effect. Automatic attempts and manually queued redelivery receive 2xx acknowledgements without duplicating that effect, while delivery IDs remain available for operational tracing.
Duplicates still appear. Check that the unique event-ID claim and the business mutation share one transaction; a separate “processed later” write can fail after the mutation.
A manual replay was ignored unexpectedly. That is correct for an already completed event. Create a new business command if an operator truly intends a second effect.
Related guides
Was this helpful?
Loading helpfulness results…
Voting saves a necessary ballot cookie for up to 180 days so you can change your answer.
Questions and replies
Ask about the steps in this guide. Questions are reviewed before publication.
Keep account details, credentials and private files out of public questions. Use private support for those.
Loading questions…
Sign in to your Dosya account to ask a question.