Webhooks: One Event Can Reach You More Than Once
A webhook announces an event, but delivery can repeat or arrive out of order. Applications must verify its origin, record event identities and make business handling idempotent rather than treating every request as a new transaction.
The Brief in One Sentence
A webhook HTTP request is not the business transaction. The same information may be delivered repeatedly although the desired side effect must occur only once.
Why It Matters
Stores and SaaS systems rely on events to fulfill orders, activate accounts, send messages and release work. If a duplicate delivery is interpreted as a new sale, costly side effects can repeat. A handler that works in a demo may fail under network interruptions.
Explain It Simply
A customer pays for one order. The event receiver times out and the provider retries. Without deduplication, two orders might ship against one payment. The failure lies in how the receiving system interprets deliveries, not necessarily in the payment service.
Evidence Map
Stripe documents automatic retries, possible duplicate deliveries and the absence of guaranteed event ordering. It recommends tracking processed event IDs and, in some cases, the underlying object ID together with event type. Signature verification requires the raw request body.
Core Mechanics
Receive HTTPS, validate signature, inspect event type, persist a unique event identity, acknowledge promptly and perform durable business processing. Out-of-order events may require fetching the current payment or invoice state. An in-memory flag cannot ensure uniqueness across restarts.
Two kinds of duplication: delivery of the same event.id twice is a transport retry. Stripe can also generate separate Event objects for the same underlying object and type; data.object.id plus event.type helps identify that case. Do not accidentally suppress distinct legitimate business operations.
Flows and Responsibilities
Information flows provider → webhook → durable ledger → asynchronous work. Business flow is payment → confirmed order → stock reservation → shipment. Evidence includes authenticated event, current entity state, processing attempt and outcome. HTTP acknowledgment is not proof that physical fulfillment completed.
Economic Logic
Duplicate processing wastes compute and may repeat refunds, credits, emails or shipments. Tracking events often costs less than reversing duplicates. Yet reliable designs also need reconciliation when downstream work fails after the endpoint acknowledges receipt.
An HTTP 2xx acknowledgment does not prove all queued work completed. Track pending tasks and provide a replay/reconciliation path.
Constraints and Failure Modes
Marking an event processed before a durable effect can lose legitimate work. Marking it too late without an atomic state transition can duplicate effects. Idempotency keys, transactions and state checks must match the consequences—especially when money moves.
If a side effect occurs at an external service without a shared transaction, a local event ledger alone may not prevent duplicates. Use a stable business reference and the partner API’s deduplication feature when available, then reconcile actual outcomes.
What People Miss
Different events can concern successive states of one payment, but arrival order is not a reliable timeline. A paid invoice event can arrive before earlier notifications. Obtain relevant current objects or enforce valid state transitions instead of assuming ordered delivery.
Critical View
Stripe documents its own products and versions; other providers may differ. Webhook idempotency alone cannot guarantee an exactly-once shipment when an external carrier or mail service lacks deduplication support. Avoid promising a globally exactly-once effect without proof of every step.
These behaviors are documented for Stripe and may differ by event format, API version and provider. Do not infer that all webhook services offer identical delivery guarantees.
Sidy’s Synthesis
My synthesis: an event is evidence of change, not a blind order to act. The truth is the verified business state plus a durable processing ledger. For a small operation, favor simple reliability: signature check, unique record, persistent work queue, idempotent side effect and periodic reconciliation. Reliability is a prerequisite for automation.
AI & Future Lens
Today AI can propose fixes but cannot provide transaction guarantees by itself. Five-year testing tools may automate failure scenarios. Ten-year agents will still duplicate actions when they ignore idempotency. Twenty years do not change the causal requirement for durable state.
Build From This
Build a no-money test lab. Deliver one fake paid-order event twice, reverse the order of two events and crash processing after receipt. Pass if exactly one business action is recorded, none is lost and replay works. Never use real Stripe secrets in a public demo.
Practical Actions
Verify signature and raw body. Persist event and business-object identifiers. Test duplicates, reversed order and failure. Reconcile unfinished actions.
Remember This
Notification ≠ transaction. HTTP 200 ≠ fulfillment. Durable deduplication before automation.
Primary sources
Facts, figures and quotations should be traceable to the sources below. Sidy's synthesis is labeled as synthesis and does not replace sourced facts.