A webhook retry should not apply a subscription change twice or send the same consequential side effect repeatedly. Treat repeated delivery as an expected condition and define which parts of processing must occur once for a given business operation.
The event's processing record and the entitlement change need a deliberate consistency relationship. A simple check-then-update sequence can still race when two deliveries arrive together.
Give events and business actions stable identities
Record the provider, account context, event identifier, affected object, processing state, and outcome. Verify the event before using it. Review the provider's duplicate-delivery contract in the current Stripe webhook documentation or the equivalent official reference for your integration.
Event identity alone may not cover every duplicate business action. Two distinct events can refer to related changes, while one event can cause several side effects. Name the operation whose repetition would be harmful and design its duplicate rule explicitly.
Rehearse a fictional plan upgrade
Suppose an upgrade grants a higher usage limit and sends a confirmation message. Deliver the same sandbox event twice, then deliver it concurrently through two workers. Verify one intended entitlement transition and the agreed messaging behaviour.
Crash processing after the entitlement update but before the event is marked complete. Retry and confirm the limit is not incremented again. Crash after marking a step complete but before sending the message, then verify the chosen recovery path does not silently lose a required notification.
The correct implementation may use transactional records, durable side-effect intents, or another architecture-specific mechanism. This article provides the failure matrix, not untested executable code. Choose the mechanism after identifying the state boundaries.
Make retries visible without making them alarming
Support should distinguish received, processing, completed, failed, and intentionally ignored events. A repeated completed event can be a normal outcome rather than a customer incident. A permanently failed transition needs an owner and reconciliation path.
Avoid logging complete sensitive payloads merely to prove deduplication. Stable references and minimal diagnostic context are often enough for routine support, with controlled access to additional evidence when necessary.
The tradeoff is bookkeeping versus reliability. Durable processing state adds storage and cleanup work, but removes ambiguity about whether retrying is safe. Retention of deduplication records must match the event and replay behaviour the integration actually supports.
The StackFlight product account gives related paid-study context. The upgrade scenario is fictional and does not assert a particular subscription implementation there.
Questions about duplicate subscription events
Is ignoring an already seen event always sufficient?
Only if its prior processing completed consistently. A seen-but-failed event may still require recovery. Track outcome rather than existence alone.
Can two workers process the same event?
They can attempt it, so the consistency mechanism must handle concurrency. Test simultaneous delivery instead of relying only on sequential retries.
What should be checked first?
Repeat one event around each crash boundary and inspect entitlement plus external side effects. Bring the result to a webhook reliability review.