How to Implement Robust Webhook Idempotency in Node.js

By Krapton Engineering · Reviewed by a senior engineer · Last updated Jun 26, 2026

Webhook providers like Stripe, Shopify, and Twilio operate on an "at-least-once" delivery guarantee. In practice, this means your server will eventually receive the same event twice due to network timeouts, provider retries, or internal load balancer hiccups. If you are not handling webhook idempotency correctly, you risk double-charging customers, sending duplicate emails, or corrupting state in your database.

TL;DR: To handle webhook idempotency in Node.js, you must implement a distributed locking mechanism using Redis to track event IDs before processing. Never rely solely on database unique constraints, as they often fail to handle race conditions during the initial request-response cycle.

Key takeaways

• At-least-once delivery is standard; assume duplicate events will occur.
• Distributed locks (via Redis) are superior to simple database flags for high-concurrency environments.
• Atomic operations using Lua scripts prevent race conditions where two processes check for an event simultaneously.
• Out-of-order events require a versioning strategy or a timestamp-check mechanism.

The Problem: Why Webhooks Fail At Least Once

In a recent client engagement, we audited a payment integration where the system was failing to process payouts correctly. The root cause was simple: the webhook provider timed out waiting for an HTTP 200 response, triggered a retry, and our Node.js backend processed the same transaction twice. This is a classic distributed systems problem. When you are handling webhook idempotency, you are essentially trying to make a non-idempotent operation (like charging a card) safe to repeat.

Most junior engineers attempt to solve this with a simple database check: if (exists) return;. However, in a high-traffic Node.js environment, two concurrent requests can both execute that check before either has inserted the record, leading to a race condition. This is why you need a more robust pattern.

The Production-Grade Approach: Atomic Redis Locking

The industry standard for handling webhook idempotency is using a distributed lock backed by Redis Lua scripts. By leveraging Redis's atomic operations, you ensure that only one instance of your worker processes a specific event ID. If another process tries to claim the same ID, it is rejected immediately.

Here is a clean implementation pattern using ioredis:

import Redis from 'ioredis';
const redis = new Redis();

async function processWebhook(eventId, payload) {
  // Attempt to set a lock for 60 seconds. NX = Only set if not exists.
  const lockKey = `webhook_lock:${eventId}`;
  const acquired = await redis.set(lockKey, 'processing', 'EX', 60, 'NX');

  if (!acquired) {
    console.log('Duplicate event detected, skipping:', eventId);
    return { status: 'ignored' };
  }

  try {
    // Perform your business logic here
    await handleBusinessLogic(payload);
    return { status: 'success' };
  } catch (error) {
    // Cleanup lock if processing fails so it can be retried
    await redis.del(lockKey);
    throw error;
  }
}

Handling Out-of-Order Events

Sometimes, events arrive out of sequence. For example, a user.created event might arrive after a user.updated event. When handling webhook idempotency, you must also consider event versioning. If your payload includes a timestamp or a version number, store that in your database alongside the event ID.

Before processing an update, compare the incoming version against the stored version. If the incoming event is older than the state you already have, discard it. This is critical for maintaining data integrity in complex Node.js backend architectures.

When NOT to use this approach

While distributed locking is robust, it adds infrastructure complexity. If your application is a low-traffic MVP or a small internal tool, a simple database unique index on an idempotency_key column might suffice. Only introduce Redis-based locking when you have high concurrency or when the cost of a duplicate operation (like executing a financial transaction) is high. Complexity is a cost; do not pay it unless you have to.

FAQ

How do I handle webhooks that don't provide a unique event ID?

If the provider doesn't send a unique ID, create a deterministic hash of the payload (e.g., using SHA-256). Use this hash as your idempotency key. This ensures that even without a native ID, you can still uniquely identify and reject duplicate requests.

Is a database UNIQUE constraint ever enough?

It is enough to prevent data corruption, but it is not enough to prevent your application code from attempting to process the logic multiple times. If your webhook triggers an external API call (like sending an email), a DB constraint won't stop the email from being sent twice. You need the application-level lock.

What if the Redis lock expires before processing finishes?

If your business logic takes longer than the lock TTL (Time-To-Live), you have a race condition. Always set your lock TTL significantly higher than your maximum expected processing time. For long-running tasks, consider a background job pattern using queues like BullMQ instead of processing webhooks synchronously.

Need a robust backend architecture?

Implementing reliable, production-grade systems requires careful attention to distributed state and race conditions. If you are building complex integrations and need expert guidance to ensure your infrastructure is scalable and error-proof, Krapton is here to help. Contact us for custom API development to build systems that handle scale without the headaches.