Duplicate Webhook

Overview

What it means and why it matters

A duplicate webhook is a repeated delivery of the same logical event from an external service to a merchant endpoint. Duplicates are normal in systems that retry delivery until acknowledgement, so consumers must be idempotent.

How it works in practice

A provider sends an event with a stable event ID and payload. If acknowledgement is lost, the provider may resend it. The merchant verifies authenticity, records or claims the event ID atomically, updates the order once and responds with an appropriate HTTP success status.

Technical detail without the jargon

Use a durable uniqueness constraint keyed by provider event ID in the correct tenant scope. Sometimes separate events have different IDs but refer to the same payment status, so fulfillment should also enforce its own once-only business key. Handle out-of-order events by comparing event versions or current state.

A deeper point to understand

The ‘exactly once delivery’ promise is difficult to guarantee across independent networks. The practical goal is at-least-once event delivery combined with exactly-once business effects where possible. A database uniqueness constraint or transactional outbox is more reliable than storing processed IDs only in application memory.

Common mistakes and limitations

Returning HTTP 200 before durable processing is secured can lose events after a crash; doing lengthy work before acknowledgement can encourage unnecessary retries. A queue-backed transaction can balance these needs.

What to check in a real payment system

Send the same signed event multiple times, then deliver a later status followed by an older one. Verify that only one irreversible business action occurs. Use a durable uniqueness constraint and return a successful acknowledgement for duplicates already safely handled.

Related concepts

Webhook, Webhook Verification, API Key.

Further reading

OWASP — Webhook Security.