Documentation

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 (do not use API key).
2. 2Capture the exact raw request body buffer.
3. 3Compute HMAC-SHA256 hash using the webhook secret.
4. 4Encode the computed hash as tightly-packed `hex`.
5. 5Use `crypto.timingSafeEqual` for comparison.

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