Webhooks, retries and idempotency

What it means

A delivery attempt and a business operation are different things. A sender may deliver the same event again, but your application may need the associated change to happen only once. Idempotency here means that repeating the event does not repeat that business effect.

A durable ledger records completed work so later deliveries can be recognized. The important question is whether that record and the effect stay consistent through a failure—not simply whether a lookup can find an event ID.

Try it

Simulation: no webhook is received and no business data is changed. Start with the baseline below, then change Delivered event ID to evt-101. Inspect the result and why it changed. Use Compare with baseline to compare the current result with the fixed initial example, not with a previous run.

0 additional business effect(s). The fixed ledger already records evt-100; all 3 deliveries are duplicates. This counts additional effects from the supplied deliveries, not any earlier work represented by the existing record.

Keep Deliveries of this event = 3 and Effect and deduplication record = atomic transaction while changing only Delivered event ID from evt-100 to evt-101.

Reset restores Delivered event ID = evt-100, Deliveries of this event = 3, and Effect and deduplication record = atomic transaction. It clears input errors and the comparison. There is no running clock or stored delivery history to rewind. Reset preserves your independent choices to open or close FAQ answers and About this model.

How it works

The ledger is useful only if its record reliably corresponds to completed work. In the atomic transaction branch, a new event's effect and completion record commit together. Later deliveries find that record and avoid applying another effect. The intermediate condition is durable evidence of completion—not merely possession of a stable event ID.

The crash before record branch breaks that connection. An effect happens, but no completion record survives. A later delivery sees the same missing record that a genuinely new event would have, so the modeled handler applies the effect again. Writing the record as a separate step after the effect therefore leaves a failure window.

Acknowledgment is another boundary. The effect and record can commit while the response to the sender is lost. That leaves the sender uncertain even though the receiver has completed the work. A durable outcome can make the retry recognizable; the missing response alone cannot tell you whether the effect happened.

The hardest misconception is that an event ID creates exactly-once processing. It only gives the handler something to recognize. The effect-and-record design determines whether that recognition is dependable, and this simulation assumes rather than tests the atomic implementation.

Worked example

This is a synthetic baseline, not a captured production observation.

The fixed ledger already contains evt-100 before these deliveries are evaluated. Each of the three deliveries therefore finds a completion record, and none enters the new-effect branch. The result is 0 additional business effect(s). The model does not reconstruct the earlier operation represented by that record, and a zero result is not evidence that a real request was authenticated or safely processed.

What changes when the condition changes

Change Delivered event ID to evt-101, keeping 3 deliveries and atomic transaction. The result is 1 additional business effect(s). The first delivery commits the effect and evt-101 record together. The remaining 2 delivery(s) find that record. The increase from zero to one represents new work being accepted, not deduplication becoming less effective.

Now keep evt-101 and 3 deliveries, but select crash before record. The result is 3 additional business effect(s). Each attempt applies its effect and then crashes before writing the record. The next attempt therefore still lacks evidence of completion and repeats the effect. The event ID has not changed; the persistence boundary has.

This failure setting deliberately assumes a crash on every attempt. It illustrates a possible duplication window, not a predicted failure rate for a real service.

In practice

Use this as a design review and isolated rehearsal, not a ready-to-run deployment recipe. Work only on a handler and test environment you own or are authorized to inspect and change. Keep test effects away from real payments, fulfillment, messages, and customer data.

1. Start read-only. Check your provider's event-identity scope, signature-verification procedure, retry behavior, and ordering contract. Trace one handler's business effect, completion record, and acknowledgment. Inspect where durable evidence of the outcome can be read without replaying the event. Keep request verification and business deduplication separate.
2. Define the boundary before changing anything. Identify exactly which effect and record are intended to commit together. If an external operation falls outside that boundary, do not assume the simulation's one-effect result applies. STOP if the prior outcome is unknown, the event's identity scope is unclear, or the claimed transaction boundary cannot be established.
3. Prepare one isolated test scope. Use one test handler, a dedicated disposable ledger, and synthetic events with no live business effects. Before any authorized sandbox change, preserve the handler's code/configuration and the test fixture's before-state. Do not point a replay at a production endpoint.
4. Verify outcomes, not just responses. For a handler claimed to provide the modeled atomic behavior, a completed-event repeat should add no effect; a new event delivered three times should leave one effect and one completion record. Inspect the effect and record separately. Test crash and lost-response handling within that sandbox. A successful HTTP response alone does not establish that the effect and record committed together.
5. Stop and restore on a mismatch. If observations differ from the intended boundary, stop sandbox replay and investigate before further changes. Restore the saved sandbox code/configuration and disposable fixture, then verify the original test behavior. Restoring code does not undo an already-issued business effect. Do not delete live deduplication records to force another attempt; any production recovery or compensating action needs its own authorized plan.

Limits and unknowns

The atomic result is conditional: both the business effect and its completion record must actually be protected by the stated transaction. If the effect is an operation in another service, that protection has not been established by this example. Authenticity, event identity scope, ordering, and concurrent locking still need implementation-specific checks. The model addresses repeated deliveries of one event, not whether different event IDs refer to the same business operation.

Selecting outcome unknown returns Hold: prior effect may have happened. Reconcile the durable event result before issuing another business mutation. This setting takes precedence even when evt-100 is selected; the model does not calculate an effect count under the selected uncertainty assumption. A timeout does not prove non-execution.

The delivery-count control supports a range of 1–10. If the current input is invalid, the previous calculated result is removed and comparison is unavailable until you correct the input or use Reset. Without JavaScript, the initial example and explanations remain readable, but the controls do not operate. No webhook, account, network request, or real ledger is inspected.

The crash-before-record count applies to an event absent from the fixed ledger. An already-recorded evt-100 is skipped, unless the selected outcome-unknown condition takes precedence. Durable event records are one strategy: an intrinsically idempotent business operation can avoid repeating an effect without relying on the exact ledger scheme shown here. Neither strategy is proved by selecting a control.

What to carry forward

Ask what durable evidence a repeated delivery will find after the first attempt—not merely whether the event has an ID. If the effect and completion record can become separated, repeats may still cause additional work. Your next step is to establish that boundary and its failure behavior in an authorized, isolated test; an unknown outcome calls for reconciliation, not another blind attempt.