Skip to content
HookDeploy

Razorpay webhooks

Last verified against Razorpay's documentation on September 27, 2026.

On this page ↓

Razorpay sends webhooks when something happens to a payment, an order, a refund, a subscription, or a payout. It expects a 2xx within 5 seconds, retries for 24 hours, and then disables the webhook entirely until you re-enable it. Replaying a missed event means raising a support ticket, one event at a time. This page covers what Razorpay sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Razorpay sends webhooks for

AreaExample eventsTypical use
Paymentspayment.authorized, payment.captured, payment.failedFulfill orders and handle failures
Ordersorder.paidMark orders paid
Refundsrefund.created, refund.processed, refund.failedRecord refunds
Subscriptionssubscription.activated, subscription.charged, subscription.halted, subscription.cancelledKeep recurring billing in sync
Disputespayment.dispute.created, payment.dispute.won, payment.dispute.lostRespond to disputes

Each webhook is a JSON POST with an event name, the account ID, and the affected entities under payload.

How Razorpay delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body
Signature headerX-Razorpay-Signature: hex HMAC-SHA256 of the raw body, keyed with the webhook’s secret
Event ID headerx-razorpay-event-id, unique per event
SuccessAny 2xx within 5 seconds
RetriesExponential backoff for 24 hours after the event was created
After 24 hoursThe webhook is disabled, and you’re emailed. Re-enable it in the Dashboard
ReplayBy support request, one event at a time, for events up to 15 days old
LimitsUp to 30 webhook URLs

Common Razorpay webhook errors and how to fix them

Signature doesn’t match

  • Parsed body. Razorpay warns that your JSON encoding can differ from theirs. Hash the raw body.
  • Rotated secret. Retries of events created before you changed the secret are still signed with the old one. Keep the old secret until those have drained.

Webhook disabled

After 24 hours of failures, Razorpay disables the webhook, and nothing arrives until you re-enable it in the Dashboard. Fix the endpoint first, then re-enable.

Timeouts cause duplicates

Razorpay waits only 5 seconds. A handler that finishes the work but responds late is treated as failed, and the event is sent again. Respond first, then process.

Duplicate events

Razorpay delivers at least once. Deduplicate on the x-razorpay-event-id header.

Why use HookDeploy with Razorpay

Never get disabled

HookDeploy captures every Razorpay webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Razorpay gets its 2xx within Razorpay’s 5-second window every time, so the webhook is never disabled, and you never need a support ticket to recover a missed event.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

One webhook, many systems

Send each Razorpay event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Razorpay can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Razorpay events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Razorpay events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then the signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Razorpay treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Razorpay’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and X-Razorpay-Signature header unchanged, so retries and replays verify like the original delivery, as long as the secret hasn’t changed since. A privacy filter that changes the stored copy used for retries and replays breaks the signature.

Razorpay’s retries, HookDeploy’s retries, and replays can all deliver the same event. Deduplicate on x-razorpay-event-id, which HookDeploy forwards unchanged.

Set up Razorpay with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Razorpay live) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. In the Razorpay Dashboard, go to Accounts & Settings, then Webhooks, and add a webhook with your HookDeploy URL, a secret, and your active events.
  4. Make a test-mode payment, and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/razorpay', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
    .update(req.body)                          // raw bytes
    .digest('hex');
  const received = req.get('x-razorpay-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);  // within 5 seconds
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({ eventId: req.get('x-razorpay-event-id'), name: event.event, payload: event.payload });
  // Deduplicate on eventId in your worker.
});

FAQ

How do I verify a Razorpay webhook?

Compute a hex HMAC-SHA256 of the raw request body using the webhook's secret, and compare it to the X-Razorpay-Signature header. Razorpay's SDKs include a helper for this.

Why was my Razorpay webhook disabled?

Razorpay retries a failing webhook for 24 hours. If it keeps failing, the webhook is disabled and you're emailed. Re-enable it in the Dashboard after fixing the endpoint.

Can I replay a Razorpay webhook?

Only by raising a support request, one event at a time, for events up to 15 days old that were sent while the webhook was enabled. Bulk replay isn't available.

How do I deduplicate Razorpay webhooks?

Use the x-razorpay-event-id header, which is unique per event and stays the same across retries.

Why does verification fail after I changed the webhook secret?

Retries of events created before the change are signed with the old secret. Keep verifying with the old secret until those retries have drained.

Does HookDeploy break Razorpay signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and X-Razorpay-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Razorpay webhooks free

Start free