Verify a Razorpay webhook's X-Razorpay-Signature HMAC-SHA256 and reconcile order and payment state idempotently.

Documented steps

1. Configure the webhook endpoint and a webhook secret in the Razorpay Dashboard under Settings > Webhooks. This secret is DISTINCT from your API Key Secret.
2. On receipt, read the RAW unparsed request body. Do not JSON.parse and re-serialise before validating, or the computed signature will not match.
3. Read the signature from the X-Razorpay-Signature header.
4. Compute HMAC-SHA256 over the raw body using the webhook secret as the key, then hex-encode the digest.
5. Compare your digest to the header value using a constant-time comparison. Reject and do not process the event if they differ. Razorpay's official SDKs expose a helper (for example Utils.verifyWebhookSignature(payload, signature, secret)).
6. Read the x-razorpay-event-id header. Persist processed event ids under a unique constraint so a retried or duplicate delivery of the same event is a no-op.
7. Parse the verified JSON body's event field (payment.authorized, payment.captured, payment.failed, order.paid) and the nested payload.payment.entity / payload.order.entity for ids and status.
8. Reconcile idempotently: upsert your local record keyed by razorpay_order_id / razorpay_payment_id and only advance status forward - ignore an authorized event that arrives after captured is already recorded.
9. For high-value reconciliation, cross-check the webhook-reported state against a live GET fetch of the payment or order via the API before finalising.
10. Return 2xx quickly once the event is durably recorded or queued, so Razorpay does not treat the delivery as failed and retry it.
11. Whitelist Razorpay's published webhook source IPs at the network layer as defence in depth alongside signature verification.
12. Official docs: https://razorpay.com/docs/webhooks/validate-test/ | https://razorpay.com/docs/webhooks/