Razorpay Webhook Signature Mismatch? Fix Guide

Problem Introduction

Razorpay signature validation fails with X-Razorpay-Signature mismatch errors.

Why It Happens

• •Payload fields arriving in different order
• •Hex encoding vs Base64 encoding mistakes
• •Using the Key ID instead of the webhook secret

Step-by-Step Fix

1. 1Store Razorpay webhook secret securely — find it at Dashboard → Webhooks, NOT the API Key.
2. 2Use express.raw() to capture the exact raw request body as a Buffer.
3. 3Compute HMAC-SHA256 of the raw body using your webhook secret.
4. 4Encode the result as lowercase hex — this is the most common mistake (devs use base64).
5. 5Use crypto.timingSafeEqual() to compare hashes — prevents timing attacks.

Working Code

Copy-paste verified examples. Use the tab that matches your stack.

const crypto = require('crypto');

app.post('/webhooks/razorpay', express.raw({ type: 'application/json' }), (req, res) => {
  const receivedSig = req.headers['x-razorpay-signature'];
  if (!receivedSig) return res.status(400).send('Missing signature header');

  // Must be 'hex' encoding — NOT 'base64'. This is the #1 mistake.
  const expectedSig = crypto
    .createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
    .update(req.body)   // Buffer from express.raw()
    .digest('hex');

  try {
    const a = Buffer.from(receivedSig, 'hex');
    const b = Buffer.from(expectedSig, 'hex');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send('Signature mismatch');
    }
  } catch {
    return res.status(401).send('Signature mismatch');
  }

  const event = JSON.parse(req.body);
  console.log('Razorpay event:', event.event);
  res.status(200).json({ received: true });
});

Common Mistakes

• •Encoding output as `base64` instead of `hex`
• •Parsing and re-stringifying the body, which removes Razorpay whitespace

Debugging Workflow

Save secret → capture raw body → hash with hex → timing safe compare.

Preventive Best Practices

• •Analyze structural formatting anomalies using the Hookmetry Reconstruction Engine.

Related Documentation