Webhook Signature Validation Guide

const crypto = require('crypto');
const express = require('express');
const app = express();

// CRITICAL: Use express.raw() — NOT express.json() — for webhook routes.
// Once JSON middleware parses the body, the raw bytes are gone.
// All major providers (Stripe, GitHub, Razorpay) sign the raw bytes.
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const receivedSig = req.headers['x-webhook-signature'];

  // req.body is a Buffer here — exactly what we need
  const expectedSig = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)               // ← raw Buffer, NOT JSON.stringify(req.body)
    .digest('hex');                 // or 'base64' — depends on the provider

  // Timing-safe comparison — prevents timing attacks
  const sigBuffer = Buffer.from(receivedSig, 'hex');
  const expBuffer = Buffer.from(expectedSig, 'hex');

  if (sigBuffer.length !== expBuffer.length ||
      !crypto.timingSafeEqual(sigBuffer, expBuffer)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Now safe to parse JSON
  const event = JSON.parse(req.body);
  console.log('Verified event:', event.type);
  res.status(200).json({ received: true });
});

// ⚠️ Common mistake: using express.json() globally and then trying to
// reconstruct the raw body with JSON.stringify(req.body) — this WILL fail
// because JSON.stringify reorders keys and drops whitespace.