Webhook Idempotency — Complete Guide

// Provider includes unique ID
const webhookPayload = {
    id: 'wh_unique_123', // Idempotency key
    event: 'payment.succeeded',
    data: { amount: 5000, customer: 'cus_123' },
};

// Consumer checks if already processed
const express = require('express');
const app = express();

const processedIds = new Set(); // In production: Redis or database

app.post('/webhooks/payment', express.json(), (req, res) => {
    const webhookId = req.body.id;

    // Check idempotency
    if (processedIds.has(webhookId)) {
        console.log(`Duplicate webhook ${webhookId}, skipping`);
        return res.status(200).send('Already processed');
    }

    // Mark as processing
    processedIds.add(webhookId);

    try {
        // Process the webhook
        handlePayment(req.body.data);
        res.status(200).send('OK');
    } catch (err) {
        // On failure, remove from processed set to allow retry
        processedIds.delete(webhookId);
        res.status(500).send('Processing failed');
    }
});

const redis = require('redis');

class IdempotencyStore {
    constructor(redisUrl) {
        this.client = redis.createClient({ url: redisUrl });
        this.ttlSeconds = 86400; // Keep for 24 hours
    }

    async isProcessed(webhookId) {
        const result = await this.client.get(`wh:idemp:${webhookId}`);
        return result !== null;
    }

    async markProcessed(webhookId) {
        await this.client.set(
            `wh:idemp:${webhookId}`,
            '1',
            { EX: this.ttlSeconds, NX: true }
        );
    }

    async markFailed(webhookId) {
        await this.client.del(`wh:idemp:${webhookId}`);
    }

    async processIfNotDuplicate(webhookId, processor) {
        // Atomic check-and-set
        const acquired = await this.client.set(
            `wh:idemp:${webhookId}`,
            'processing',
            { EX: 300, NX: true } // 5 minute processing lock
        );

        if (!acquired) {
            const status = await this.client.get(`wh:idemp:${webhookId}`);
            if (status === '1') {
                return { status: 'duplicate', action: 'skipped' };
            }
            if (status === 'processing') {
                return { status: 'in_progress', action: 'wait' };
            }
        }

        try {
            await processor();
            await this.client.set(
                `wh:idemp:${webhookId}`,
                '1',
                { EX: this.ttlSeconds }
            );
            return { status: 'success', action: 'processed' };
        } catch (err) {
            await this.client.del(`wh:idemp:${webhookId}`);
            throw err;
        }
    }
}

-- PostgreSQL idempotency table
CREATE TABLE webhook_idempotency (
    webhook_id VARCHAR(255) PRIMARY KEY,
    status VARCHAR(20) NOT NULL DEFAULT 'processing',
    processed_at TIMESTAMP,
    response_code INTEGER,
    error_message TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_webhook_idempotency_status
    ON webhook_idempotency(status);

-- Consumer logic with database
async function processWithDbIdempotency(webhookId, processor) {
    const { rows } = await db.query(
        `INSERT INTO webhook_idempotency (webhook_id, status)
         VALUES ($1, 'processing')
         ON CONFLICT (webhook_id) DO NOTHING
         RETURNING status`,
        [webhookId]
    );

    if (rows.length === 0) {
        // Already exists
        const { rows: existing } = await db.query(
            'SELECT status FROM webhook_idempotency WHERE webhook_id = $1',
            [webhookId]
        );
        return { duplicate: true, status: existing[0].status };
    }

    try {
        await processor();
        await db.query(
            `UPDATE webhook_idempotency
             SET status = 'completed', processed_at = NOW()
             WHERE webhook_id = $1`,
            [webhookId]
        );
        return { duplicate: false, status: 'completed' };
    } catch (err) {
        await db.query(
            `UPDATE webhook_idempotency
             SET status = 'failed', error_message = $1
             WHERE webhook_id = $2`,
            [err.message, webhookId]
        );
        throw err;
    }
}

// Complete idempotent webhook handler
class IdempotentWebhookHandler {
    constructor(options = {}) {
        this.store = options.store; // Redis, DB, or in-memory
        this.processor = options.processor;
    }

    async handle(req, res) {
        const webhookId = req.body.id || req.headers['x-webhook-id'];
        const idempotencyKey = req.headers['idempotency-key'];

        const key = webhookId || idempotencyKey;

        if (!key) {
            return res.status(400).send('Missing idempotency key');
        }

        try {
            const result = await this.store.processIfNotDuplicate(
                key,
                () => this.processor(req.body)
            );

            if (result.status === 'duplicate') {
                return res.status(200).json({
                    status: 'duplicate',
                    message: 'Already processed',
                });
            }

            res.status(200).json({ status: 'accepted' });
        } catch (err) {
            console.error(`Webhook ${key} processing failed:`, err);
            res.status(500).send('Processing error');
        }
    }
}

// Usage
const handler = new IdempotentWebhookHandler({
    store: new RedisIdempotencyStore('redis://localhost:6379'),
    processor: async (payload) => {
        // Business logic
        await chargeCustomer(payload.data.customerId, payload.data.amount);
        await sendReceipt(payload.data.customerId);
    },
});

app.post('/webhooks/stripe', (req, res) => handler.handle(req, res));