Webhook Security: HMAC Signatures, Replay Protection, and Safe Idempotency

Security tutorial - IT technology blog
Security tutorial - IT technology blog

Context & Why: The Hidden Risks Behind Webhook Endpoints

Modern microservices depend heavily on external event hooks. Whenever a customer buys a subscription, checks out a cart, or pushes code, providers like Stripe, Shopify, and GitHub dispatch an HTTP POST payload to your API.

But here lies the vulnerability: those ingestion endpoints must remain exposed to the public internet. Any open port or unguarded route invites probing. Attackers can forge payloads, mimic third-party gateways, intercept transit data, or trigger cascading duplicate actions across your backend.

Locking down these endpoints means neutralizing three critical attack vectors:

  • Spoofing and Tampering: Malicious actors send fabricated events—such as a forged invoice.paid payload—hoping to trigger free order fulfillments. We prevent this using HMAC (Hash-based Message Authentication Code) SHA-256 signatures pegged to a shared secret key.
  • Replay Attacks: A network eavesdropper captures a legitimate, cryptographically valid request and blasts it against your server hours later. Even with signature checks passing, your database might process extra credits or double-ship merchandise. We thwart this by enforcing a strict timestamp tolerance window (typically 300 seconds).
  • Duplicate Delivery: Transient network drops or upstream retries often trigger identical dispatches. If Stripe retries five times over an hour due to a brief 504 gateway timeout, your system cannot run the business logic five times. We solve this by registering idempotency keys inside an in-memory cache like Redis using atomic operations.

Installation: Preparing the Environment and Dependencies

We’ll construct a production-ready webhook receiver with Node.js 20+, Express, and Redis 7 for low-latency atomic locks.

Set up a dedicated project workspace:

mkdir secure-webhook-receiver
cd secure-webhook-receiver
npm init -y

Add ioredis for fast key-value operations and dotenv for runtime secrets:

npm install express ioredis dotenv

Spin up a local Redis instance using Docker if you don’t already have one running:

docker run -d --name redis-webhook -p 6379:6379 redis:7-alpine

Configuration: Implementing HMAC, Timestamp Validation, and Idempotency

One non-negotiable rule governs webhook security: never verify signatures against parsed JSON. Parsing a payload reorders keys, normalizes whitespace, and strips byte-level formatting. Those tiny mutations instantly invalidate the cryptographic hash. You must capture and sign the exact incoming byte stream.

Store your configuration variables in a local .env file. The shared secret requires a high-entropy string—ideally 32 bytes (64 hex characters):

PORT=3000
WEBHOOK_SECRET=7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Hardcoded secrets or short dictionary words expose your endpoints to offline brute-force attacks. When provisioning production credentials, you can quickly generate cryptographically secure 256-bit hex strings using the browser-based password generator at toolcraft.app/en/tools/security/password-generator. Because it runs client-side Web Crypto APIs without network transmissions, the generated keys never touch an external wire.

Assemble the complete verification engine inside server.js:

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const Redis = require('ioredis');

const app = express();
const redis = new Redis({
  host: process.env.REDIS_HOST || '127.0.0.1',
  port: parseInt(process.env.REDIS_PORT, 10) || 6379
});

// Preserve raw byte stream for cryptographic verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

// Verification middleware: validates signature, timestamp drift, and payload integrity
function verifyWebhookSignature(req, res, next) {
  const signatureHeader = req.headers['x-webhook-signature'];
  const timestampHeader = req.headers['x-webhook-timestamp'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!signatureHeader || !timestampHeader) {
    return res.status(401).json({ error: 'Missing security headers' });
  }

  // 1. Guard against Replay Attacks: reject timestamps deviating by > 300 seconds
  const currentTime = Math.floor(Date.now() / 1000);
  const requestTime = parseInt(timestampHeader, 10);
  const maxToleranceSeconds = 300; // 5-minute drift ceiling

  if (isNaN(requestTime) || Math.abs(currentTime - requestTime) > maxToleranceSeconds) {
    return res.status(400).json({ error: 'Timestamp outside acceptable tolerance window' });
  }

  // 2. Compute HMAC SHA-256 over concatenated timestamp and raw bytes
  const computedHex = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.`)
    .update(req.rawBody)
    .digest('hex');

  // 3. Constant-time comparison to prevent side-channel timing attacks
  const signatureBuffer = Buffer.from(signatureHeader, 'hex');
  const expectedBuffer = Buffer.from(computedHex, 'hex');

  if (
    signatureBuffer.length !== expectedBuffer.length ||
    !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)
  ) {
    return res.status(403).json({ error: 'Invalid webhook signature' });
  }

  next();
}

// Ingestion route with atomic Redis idempotency locks
app.post('/api/webhooks/orders', verifyWebhookSignature, async (req, res) => {
  const eventId = req.headers['x-webhook-id'] || req.body.id;

  if (!eventId) {
    return res.status(400).json({ error: 'Missing idempotency event ID' });
  }

  // 4. Atomic lock: Redis SET key value EX 86400 NX
  const idempotencyKey = `webhook:processed:${eventId}`;
  const acquired = await redis.set(idempotencyKey, 'processing', 'EX', 86400, 'NX');

  if (!acquired) {
    // Event is already executing or completed; acknowledge without duplicating side effects
    return res.status(200).json({ status: 'ignored', message: 'Event already processed or in-flight' });
  }

  try {
    // Process business domain logic (e.g., fulfill digital goods, notify billing)
    console.log(`Processing event ${eventId}:`, req.body);

    // Transition state from 'processing' to 'completed'
    await redis.set(idempotencyKey, 'completed', 'EX', 86400);

    return res.status(200).json({ status: 'success', eventId });
  } catch (error) {
    // Evict key on unexpected crash so upstream provider retries succeed
    await redis.del(idempotencyKey);
    return res.status(500).json({ error: 'Internal processing failure' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook receiver listening on port ${PORT}`);
});

Verification & Monitoring: Testing Scenarios and Production Guardrails

Before exposing your endpoint to live traffic, validate each security mechanism using targeted curl tests.

1. Testing a Valid, Signed Request

Generate a valid HMAC hash using OpenSSL with your current Unix timestamp and a test JSON payload:

SECRET="7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b"
TIMESTAMP=$(date +%s)
PAYLOAD='{"id":"evt_order_9981","type":"payment.succeeded","amount":4900}'

# Generate valid HMAC-SHA256 signature
SIGNATURE=$(printf "%s.%s" "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

# Dispatch signed payload
curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${TIMESTAMP}" \
  -H "x-webhook-signature: ${SIGNATURE}" \
  -H "x-webhook-id: evt_order_9981" \
  -d "${PAYLOAD}"

Your receiver will respond with HTTP/1.1 200 OK and body {"status":"success","eventId":"evt_order_9981"}.

2. Testing Replay Attack Mitigation

Simulate an attacker resending captured traffic. Generate a timestamp 10 minutes (600 seconds) in the past:

EXPIRED_TIMESTAMP=$(( $(date +%s) - 600 ))
EXPIRED_SIG=$(printf "%s.%s" "$EXPIRED_TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${EXPIRED_TIMESTAMP}" \
  -H "x-webhook-signature: ${EXPIRED_SIG}" \
  -H "x-webhook-id: evt_order_9982" \
  -d "${PAYLOAD}"

The server rejects the outdated timestamp immediately: HTTP/1.1 400 Bad Request with {"error":"Timestamp outside acceptable tolerance window"}.

3. Testing Idempotency

Re-fire the original valid request (with evt_order_9981). Because Redis already holds that key, your app skips processing and returns:

{"status":"ignored","message":"Event already processed or in-flight"}

This single guarantee stops accidental double-charges and redundant inventory deductions.

Ongoing Monitoring Metrics

Configure alerts in Prometheus, Datadog, or CloudWatch around three critical signals:

  • 401/403 Error Rates: An abrupt spike usually flags a mismatched shared secret, rotated API credentials that failed to sync, or active probe traffic. Investigate anything higher than 0.1% of total volume.
  • Duplicate Event Ratio: Expect normal baseline duplicates between 1% and 3%. A sudden jump above 5% often means downstream processing takes longer than the caller’s timeout threshold (Stripe times out at 5 seconds; GitHub allows 10 seconds), triggering unnecessary automated retries.
  • P95 Ingestion Latency: Keep webhook response times under 250ms. If database transactions or third-party API calls push latency higher, offload the workload to an asynchronous queue like BullMQ, SQS, or RabbitMQ immediately after acknowledging receipt.
Share: