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.

Four panels show reading the event and delivery IDs, claiming the event ID transactionally, skipping a repeated event, and tracing each delivery attempt separately.
Four panels show reading the event and delivery IDs, claiming the event ID transactionally, skipping a repeated event, and tracing each delivery attempt separately. Open full-size screenshot.

Steps

  1. Verify X-Dosya-Signature over the raw body, then read X-Dosya-Event-Id and confirm it matches the body’s top-level id. Treat an absent or conflicting value as malformed input.
  2. 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.
  3. 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-Id differs.
  4. 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.
  5. 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 original evt_… event ID.
  6. 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.

Reference for “Deduplicate webhook deliveries”: Dosya REST API overview page with Get API Key and View SDKs links.
Reference for “Deduplicate webhook deliveries”: Dosya REST API overview page with Get API Key and View SDKs links. Open full-size screenshot.

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.

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.

    Check the outcome before you retry

    Use these shared checks when a task needs a second look.