n8n Webhook Idempotency Guard with Data Table Ledger

Stop duplicate webhook side effects with an n8n idempotency guard backed by a Data Table ledger

This n8n automation prevents repeated webhook deliveries from triggering payments, notifications, database writes, or other one-time actions more than once—by storing scoped idempotency keys in an n8n Data Table.

What this workflow does

• Receives requests via a Webhook node that include an idempotency_key, optional scope, and a payload.
• Builds a collision-resistant ledger key by combining scope and idempotency_key.
• Checks the ledger in an n8n Data Table for an existing unexpired record to decide whether this delivery is a duplicate.
• Records the decision: creates a new ledger entry, refreshes an expired record, or increments counters for duplicates.
• Audits duplicates by increasing duplicate_count and updating last_seen_at.
• Returns a JSON response containing allow_processing, the decision/action, and ledger metadata so downstream steps continue only when allow_processing is true.

Use cases

• Protect a payment-triggering flow from repeated webhook retries by only allowing the first delivery per idempotency_key (and optional scope).
• Ensure notification workflows don’t spam users when upstream systems resend the same event.
• Avoid duplicate database writes by gating side effects behind allow_processing.

Technical details

• Data Table ledger named webhook_idempotency with columns: ledger_key, scope, idempotency_key, status, first_seen_at, last_seen_at, expires_at, duplicate_count.
• Configured TTL hours, default scope, and maximum key length in the guard configuration step.
• Nodes used: Webhook, Data Table, Code, Switch, and a Sticky Note for guidance.

Setup tip: copy the production webhook URL for /webhook/idempotency-guard and send POST requests with idempotency_key (optionally scope and payload).