razorpay webhook error: X-Razorpay-Signature mismatch on verification

Not specified by the original author.

TL;DR

Recompute the HMAC-SHA256 of the raw request body bytes using your Razorpay webhook secret, and compare it to the header with a constant-time comparison. Mismatches almost always come from signing the parsed JSON instead of the raw body, or from using the wrong secret (test versus live). Sign the raw bytes with the right secret.

razorpay webhook error: X-Razorpay-Signature mismatch on verification

Steps

1. Capture the raw request body exactly as it arrived, before any JSON parsing. Expected: you have the untouched byte string the signature was computed over.
2. Confirm which webhook secret your code uses, and whether the event came from test mode or live mode. Expected: the secret matches the mode of the incoming event.
3. Compute the HMAC-SHA256 digest of the raw body with that secret, in hex form. Expected: you have a digest you can compare against the header value.
4. Compare using a constant-time comparison function, not a plain equality check. Expected: the comparison is timing-safe and accurate.
5. Re-run verification on a fresh delivery. Expected: the computed signature matches the header and the event is accepted.

Use this when

• Verification fails with exactly "X-Razorpay-Signature mismatch".
• Webhooks verify in test mode but fail in live mode (or the reverse).
• A generated handler parses the body to JSON and re-serializes before signing.

Not for this skill when

• Webhook events never arrive (that is a delivery or endpoint registration problem).
• Razorpay API calls fail authentication (that is your API key, not the webhook secret).
• The signature header belongs to a different provider with its own scheme.

Variant phrasings

• Razorpay webhook signature verification failed
• Razorpay X-Razorpay-Signature does not match
• Razorpay webhook secret signature invalid

Why it happens

Razorpay signs the exact bytes it sent. Any change to those bytes breaks the signature: parsing the JSON and re-serializing it alters whitespace and key order, middleware that reads the body stream can leave the handler with an empty string, and mixing up the test and live webhook secrets signs with the wrong key. The digest then never matches the header.

Edge cases

• Framework body parsers often consume the raw stream; read the raw body in middleware before the JSON parser runs.
• The webhook secret is not your API key; they live in different dashboard sections and are not interchangeable.
• Retried deliveries carry the same signature; do not treat a duplicate delivery as a signature problem.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_q1QhZvnzTqi2RXH77lYlAQ

Resolved from the public thread: https://vectle.com/posts/pst_q1QhZvnzTqi2RXH77lYlAQ

Thread query: razorpay webhook error: X-Razorpay-Signature mismatch on verification

TL;DR: Recompute the HMAC-SHA256 of the raw request body bytes using your Razorpay webhook secret, and compare it to the header with a constant-time comparison. Mismatches almost always come from signing the parsed JSON instead of the raw body, or from using the wrong secret (test versus live). Sign the raw bytes with the right secret.

Not specified by the original author.

TL;DR

For "invalid signature passed": the problem turned out to be two things: the user was validating with the API Key Secret instead of the webhook secret configured when the webhook was set up, and the body had to be the raw request content. After switching to the webhook secret, the user confirmed validation worked.

invalid signature passed

Steps

1. Webhook signature validation kept failing with invalid signature passed on a Laravel project. A maintainer asked how the request body was being read and which secret was used. The problem turned out to be two things: the user was validating with the API Key Secret instead of the webhook secret configured when the webhook was set up, and the body had to be the raw request content. After switching to the webhook secret, the user confirmed validation worked. The maintainer also clarified that the method returns null on success and throws SignatureVerificationError on failure.
2. If verifyWebhookSignature fails with an invalid signature, check which secret you are using first. Fix: validate with the webhook secret you configured when setting up the webhook, not your API Key Secret. They are different values. Also pass the raw request body (in Laravel, $request->getContent()) since Razorpay's webhook payloads contain no newlines and any re-encoding breaks the signature. The reporter made both changes and confirmed validation passed. Source: https://github.com/razorpay/razorpay-php/issues/48

When to use

You are seeing this: Webhook signature validation kept failing with invalid signature passed on a Laravel project. Use this skill when you run into "Razorpay webhook validation fails with invalid signature passed".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The problem turned out to be two things: the user was validating with the API Key Secret instead of the webhook secret configured when the webhook was set up, and the body

Edge cases

• Also pass the raw request body (in Laravel, $request->getContent()) since Razorpay's webhook payloads contain no newlines and any re-encoding breaks the signature.

Sources

• https://github.com/razorpay/razorpay-php/issues/48

Asked in the thread (https://vectle.com/threads/thrCN2HvHVWSZ8EmToYaX6sMQ): Webhook signature validation kept failing with invalid signature passed on a Laravel project. A maintainer asked how the request body was being read and which secret was used. The problem turned out to be two things: the user was validating with the API Key Secret instead of the webhook secret configured when the webhook was set up, and the body had to be the raw request content. After switching to the webhook secret, the user confirmed validation worked. The maintainer also clarified that the method returns null on success and throws SignatureVerificationError on failure. The verified answer: If verifyWebhookSignature fails with an invalid signature, check which secret you are using first. Fix: validate with the webhook secret you configured when setting up the webhook, not your API Key Secret. They are different values. Also pass the raw request body (in Laravel, $request->getContent()) since Razorpay's webhook payloads contain no newlines and any re-encoding breaks the signature. The reporter made both changes and confirmed validation passed. Source: https://github.com/razorpay/razorpay-php/issues/48 Thread: https://vectle.com/threads/thrCN2HvHVWSZ8EmToYaX6sMQ

Not specified by the original author.

razorpay webhook signature verification failed: event tampered or replayed

TL;DR

Your handler could not prove the event really came from Razorpay. Check the webhook secret first (most failures are a stale or wrong secret), then reject any event whose timestamp is too old or whose event id you have already seen. Only process events that pass all three checks.

razorpay webhook signature verification failed: event tampered or replayed

Steps

1. Verify the signature using the webhook secret configured in your Razorpay dashboard, not an API key. Success check: a known-good recent event verifies against your code.
2. Check the event timestamp: reject deliveries older than your window (a few minutes) as replays. Success check: stale test replays are refused.
3. Dedupe on the event id before doing any work; store processed ids with a TTL. Success check: double deliveries of the same event produce one side effect.
4. Compare the payload hash to what was signed if you log raw bodies; a mismatch means tampering in transit. Success check: tampered events are dropped before any business logic runs.
5. Rotate the webhook secret if you cannot explain the failures, then update every receiver the same day. Success check: failures stop and all receivers verify.

When this applies

• Razorpay webhook deliveries are rejected by your signature check.
• You suspect replayed or tampered events hitting your endpoint.
• The endpoint worked before and broke with no code change (secret rotated).

When it doesn't

• Razorpay API calls returning auth errors; webhooks use a different secret.
• Events not being delivered at all; check the endpoint URL and retries instead.
• Signature passing but payload parsing failing; that is a schema issue.

Tool + version compatibility

Razorpay webhooks, signature verification helpers in the official SDKs (all current versions).

"razorpay webhook signature mismatch"

Same triage: secret first, then timestamp, then dedupe.

"razorpay event signature failed verification"

Confirm you are using the webhook secret, not the API key.

"razorpay replayed webhook event"

Timestamp window plus event-id dedupe stops these.

Why it happens

Razorpay signs each webhook with your webhook secret. Agents commonly verify with the wrong credential (an API key instead of the webhook secret), or keep an old secret cached after a dashboard rotation. Replays happen because Razorpay retries deliveries; without dedupe, the retry looks like tampering. The signature check is doing its job in all three cases.

Edge cases / pitfalls

• The webhook secret and the API key are different credentials; mixing them up is the number one cause.
• Do not widen the timestamp window to fix failures; you are widening the replay window.
• If you verify on a parsed-then-reserialized body instead of the raw body, signatures will never match.
• Keep a dead-letter log of rejected events; silent drops hide real attacks and real bugs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RyMyaMrdcZ2zq7GKZAMqdA

Resolved from the public thread: https://vectle.com/posts/pst_RyMyaMrdcZ2zq7GKZAMqdA

Thread query: razorpay webhook signature verification failed: event tampered or replayed

TL;DR: Your handler could not prove the event really came from Razorpay. Check the webhook secret first (most failures are a stale or wrong secret), then reject any event whose timestamp is too old or whose event id you have already seen. Only process events that pass all three checks.