Production Webhook Pipelines with Node.js and Stripe: Complete Step-by-Step Setup and Idempotency Guide

To build an enterprise-grade Stripe webhook handler in Node.js with zero duplicate billing events, you must capture the unparsed HTTP request body as a raw Buffer using express.raw({ type: 'application/json' }), verify cryptographic authenticity with stripe.webhooks.constructEvent(), and enforce distributed idempotency via Redis SET key value NX EX 86400. Because payment processors retry unacknowledged webhook deliveries with exponential backoff over 72 hours, acknowledging immediately with res.status(200).json({ received: true }) before delegating to asynchronous message queues eliminates gateway timeout retries and race conditions.

The Core Vulnerabilities in Naive Webhook Handlers

Most webhook implementations fail in production for two reasons: (1) body-parsing middleware mutates or stringifies incoming JSON, invalidating cryptographic HMAC-SHA256 signature verification; and (2) payment networks guarantee at-least-once delivery, resulting in duplicate charges or provisioning when network jitter delays acknowledgement receipts.

Step 1: Configure Raw Body Middleware in Express

Webhook signature checking requires the exact byte sequence received over the wire. Mount raw buffer middleware specifically on your webhook route before applying global body parsers:

import express from 'express';
import Stripe from 'stripe';
import { Redis } from 'ioredis';

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { apiVersion: '2025-01-27.acacia' });
const redis = new Redis(process.env.REDIS_URL);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

// Webhook endpoint MUST receive raw buffer
app.post('/api/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;

    try {
        event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
    } catch (err) {
        console.error(`⚠️ Webhook signature verification failed: ${err.message}`);
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Step 2 & 3: Idempotency check & processing
    const isProcessed = await acquireIdempotencyLock(event.id);
    if (!isProcessed) {
        // Acknowledge duplicate event without re-executing business logic
        return res.status(200).json({ received: true, note: 'Duplicate event skipped' });
    }

    // Acknowledge receipt to Stripe immediately
    res.status(200).json({ received: true });

    // Step 4: Dispatch event to asynchronous queue
    await dispatchToQueue(event);
});

Step 2: Enforce Atomic Distributed Idempotency via Redis

Use Redis atomic SET NX EX (Set if Not Exists with Expiration) to establish an atomic lock across microservice instances:

async function acquireIdempotencyLock(eventId: string): Promise<boolean> {
    const lockKey = `webhook:lock:${eventId}`;
    // Lock expires in 24 hours (86400 seconds)
    const result = await redis.set(lockKey, '1', 'EX', 86400, 'NX');
    return result === 'OK';
}

Step 3: Prevent Container OOM in High-Throughput Queue Workers

When running webhook consumers that invoke heavy LLM pipelines or database migrations, worker pods frequently exceed memory limits under sudden traffic bursts. Review our guide on Docker Exit Code 137 in Kubernetes and Deep Learning to tune cgroup allocations and worker concurrency.

Step 4: Orchestrating Downstream AI Agents

If your webhook pipeline feeds customer events into autonomous conversational agents, choosing a deterministic orchestrator prevents runaway API loops. Compare architecture patterns in our benchmark of LangGraph vs AutoGen vs CrewAI, and safeguard cyclic state transitions using our playbook on LangGraph Recursion Limit Reached.