Prevent Webhook Replays from Duplicating Internal Work
Use a replay timeline that separates receipt, claims, uncertain effects and completion while preserving one intended internal outcome.
10/24/20263 min read
A webhook delivery is not necessarily a new business event. Providers may resend an event after a missing acknowledgment, and operators may replay it during recovery. If each arrival starts fresh work, one source change can create several internal tasks.
Build a replay ledger around the provider's documented event identity and your own processing state. Stripe documents possible duplicate webhook deliveries. Its specific identification rules must not be copied blindly to another service; the actual provider contract controls what counts as the same event.
Separate receipt from completed processing
Use distinct states for received, validated, claimed, effect uncertain, completed and rejected. Marking an event completed before the business effect is established can lose work. Marking it only after the effect without controlling concurrent claims can permit duplicates. The engineering design must address both boundaries.
Authentication of incoming events is a separate security requirement. Use the provider's supported verification mechanism through an approved implementation. A familiar event ID or a matching payload is not proof that a request is genuine. This article describes ledger behavior, not credential setup or a public endpoint deployment.
A synthetic replay timeline
The fictional provider sends event EV70, meaning that an approved internal research packet is ready. The consumer should create one review item for packet P11. All events and destinations in this example are mocks.
Delivery D1: EV70 validates and is claimed by worker W1. Ledger records business operation O70 before the consequential attempt.
Delivery D2: EV70 arrives while W1 is active. Expected: recognize the existing claim; no second worker creates the review item.
Effect step: W1's request is accepted by the mock destination, but the response is lost. Ledger becomes effect uncertain, not failed-before-action.
Delivery D3: EV70 arrives again. Expected: route to reconciliation of O70, not another creation attempt.
Reconciliation: destination item R70 is verified. Ledger becomes completed with its reference.
Delivery D4: EV70 arrives after completion. Expected: record duplicate receipt as needed; no repeated business effect.
The usable artifact is a timeline ledger with delivery reference, event identity, processing claim, operation identity, observed effect and disposition. It makes clear that delivery count and completed-work count are different measures.
Test worker failure and stale claims
A worker can stop after claiming an event but before attempting the effect. Define how another authorized worker determines whether the claim is abandoned and whether execution occurred. Do not simply expire a claim and assume no action happened. The handoff needs evidence from the operation ledger and destination where available.
Test a concurrent arrival, a crash before submission and a crash after acceptance. Those cases should not collapse into one generic retry path. Use atomic claim or equivalent supported concurrency controls appropriate to the application; a read-then-write check without protection can race.
Handle changed payloads carefully
If the same event identity arrives with different material content, hold it as a conflict under the provider's semantics. Do not overwrite the original record and pretend it was always the new payload. A distinct legitimate event may concern the same object, so object ID alone can also be too broad for duplicate handling.
Document the retention window for replay evidence and the provider's possible redelivery window. When old evidence has expired, the system needs a safe policy, such as authoritative-state reconciliation, rather than automatic treatment as a new action. Retention must also respect the data involved.
Close with verified outcomes
The operator report should state how many deliveries were observed, how many distinct events were accepted, how many business effects were confirmed and which outcomes remain uncertain. A successful acknowledgment is not proof that the internal task was created correctly.
The finished replay test demonstrates one intended task across repeated deliveries and preserves unresolved effects for review. It does not promise exactly-once processing across every failure or replace source authentication, authorization and destination-specific duplicate controls.
If you are also choosing research access, ask about Leads Automation’s independent Sales Navigator offer at US$15/month on WhatsApp. Confirm the available plan, eligibility and terms before ordering; Leads Automation is not affiliated with LinkedIn. This is not LinkedIn’s official price or an assurance that any particular integration is included.