Test the replay, not the happy path.

The best key is normally created by the system that owns the event: a payment event ID, order ID plus operation, form submission ID, or message ID. Preserve that value at the webhook boundary. Do not replace it with an n8n execution ID, because a retry may create a different execution while representing the same source event. Do not generate a random UUID inside the workflow, because every delivery would receive a new identity and every duplicate would look legitimate.

A payload hash can be a fallback only when the business meaning is understood. Hashes require canonical serialization; otherwise key order, irrelevant timestamps, or formatting can create different hashes. The opposite error matters too: two legitimate orders may have identical amounts and customer fields. A collision that suppresses a real event is not safer than a duplicate action.

The repository behind this page includes a dependency-free Node.js harness and six automated tests. It does not call n8n, a payment processor, or any external service. Its purpose is narrower: prove the decision contract before adapting it to a real durable store. The harness claims a stable key, counts external-action attempts, records a completed receipt, and refuses to automatically replay an ambiguous post-action failure.

const harness = createWebhookReplayHarness();

await harness.deliver({ eventKey: "evt_100" });
await harness.deliver({ eventKey: "evt_100" });

assert.equal(harness.snapshot().externalActionCount, 1);

The concurrent test pauses the first external action after its claim, delivers the same event again, and verifies that the second call receives suppressed_in_flight. Another test fails before the effect and confirms that a retry can complete once. The most important negative test simulates a crash after the effect: the next delivery receives manual_review, and the action count stays at one. That fail-closed result is less convenient than an automatic retry, but it avoids converting uncertainty into a known duplicate.

1. 01

   Receive and authenticate

   Use the production webhook URL and the authentication supported by the sender. Reject malformed or unauthenticated requests before they can create a claim record.

2. 02

   Normalize the operation key

   Preserve the source ID and combine it with the exact business action when one event can legitimately trigger several independent effects.

3. 03

   Perform an atomic claim

   Use a database or service that can enforce uniqueness in one operation. Route completed, in-flight, ambiguous, and new outcomes separately.

4. 04

   Call the external system once

   Pass the same idempotency key downstream when its API supports one. Keep credentials here, not in the public webhook or validation branch.

5. 05

   Commit and acknowledge

   Save the downstream identifier and completed receipt, then return the acknowledgement. If receipt storage fails after the action, record ambiguity instead of assuming failure.

n8n's Remove Duplicates node can compare current items with data from previous executions, and that can be a useful filter. Treat it as one layer rather than the entire contract. Confirm what fields it compares, how long history is retained, whether all action paths pass through it, and what happens under concurrent execution. A durable unique claim close to the side effect is easier to reason about than a visual deduplication step far upstream.

A replay-safe workflow should make its boundary inspectable. For each delivery, record a correlation ID, a redacted or opaque event key, the operation, claim result, current state, attempt number, downstream action ID when available, and the final route. Include enough timing to reconstruct order without treating wall-clock time as the identity. Protect those records using the same privacy and access rules as the underlying business event.

Alerts should distinguish a suppressed replay from an ambiguous event. A suppressed completed replay is often healthy evidence that the design worked. An ambiguous event is actionable because a person or reconciliation process must determine whether the remote system acted. Counting both as generic failures makes the dashboard louder and the important state harder to see.

n8n documents separate test and production webhook URLs and supported authentication options for the Webhook node. Its Remove Duplicates node documentation describes comparing items with data from previous executions. The execution documentation describes retrying a failed workflow with current or original workflow data, and the error-handling guide describes Error Trigger workflows. Those capabilities support the implementation, but none removes the need to define and test the business-side idempotency invariant.