Independent research & analysis on payment security Search
paymentsecuritypros.com Payment Security Insights
Best Practices & How-To

Razorpay vs Cashfree Webhooks: Signature Verification, Duplicate Events and Outage Recovery

A webhook is where a payment event becomes a business action: an order is marked paid, a parcel is packed, a wallet is credited. This guide compares how Razorpay and Cashfree document that boundary: signature verification, retries, duplicate and out-of-order events, and recovery after your endpoint has been down. Dashboard access controls, fraud tooling and basic checkout integration are out of scope.

Everything comes from each provider’s current public developer documentation. Sources checked in November 2026. Razorpay examples apply to account-level payment webhooks. Cashfree details apply to Payments webhooks in its “latest” documentation (versions 2023-08-01, 2025-01-01 and 2026-01-01). Code is illustrative; test it against your own account.

Quick answer: Both providers sign webhooks with HMAC-SHA256 over the raw request body and both deliver at least once, so duplicates are expected on either side. Razorpay sends the signature in X-Razorpay-Signature, identifies each event with x-razorpay-event-id, expects a 2xx response within 5 seconds, retries with exponential backoff for 24 hours and then disables the webhook with an email alert. Cashfree signs the timestamp plus the raw body, sends x-webhook-signature and x-webhook-timestamp, and offers configurable retry schedules. Neither provider’s webhook alone should trigger fulfilment without an idempotent state check.

Key Takeaways

  • Razorpay documents HMAC-SHA256 signature verification, an event ID (x-razorpay-event-id) for duplicate detection and retry behaviour that lasts 24 hours from event creation.
  • Successful processing still requires idempotency, monitoring and recovery checks on your side. A 2xx response proves receipt, not that the order was fulfilled correctly.
  • Delivery order is not guaranteed. Razorpay states that payment.captured can arrive before payment.authorized.
  • A browser redirect is never proof of payment with either provider.

What goes wrong when a payment notification fails?

A customer pays ₹2,499 by UPI and closes the tab before the redirect returns. Your webhook endpoint is mid-deployment and returns HTTP 502, so the order stays “pending”. Support refunds the customer manually. Then the provider’s retry arrives, your now-healthy endpoint accepts it, and the warehouse ships. You have refunded and shipped the same sale.

Three channels were involved, each with a different job:

  • Browser redirect or callback: tells you the customer came back. It can be lost or tampered with. Use it for a “confirming your payment” page, not to fulfil.
  • Server-to-server webhook: a signed event pushed to your endpoint. It is the primary trigger for state changes, but can be delayed, repeated or out of order.
  • Payment status API: you pull the current state. Razorpay suggests polling payment APIs for business-critical, synchronous cases. Use it to resolve anything uncertain.

The fix is not “better uptime”. It is a durable order record that only moves forward, plus reconciliation before any manual refund. Our payment API and webhook security checklist covers the general controls; this article focuses on the two providers’ specific behaviour.

How do Razorpay and Cashfree webhooks compare?

Behaviour Razorpay (payment webhooks) Cashfree (Payments webhooks, latest docs)
Signature header X-Razorpay-Signature (sent when a webhook secret is set) x-webhook-signature, with x-webhook-timestamp
Algorithm and signed content HMAC-SHA256 of the raw body, keyed with the webhook secret; hex digest HMAC-SHA256 of timestamp + raw body, Base64-encoded; code samples use the Client Secret
Raw body requirement “Do not parse or cast the webhook request body” Signature is on the raw payload; parsing can change decimals (170.00 to 170)
Event or delivery identifier x-razorpay-event-id, unique per event Idempotency header from version 2025-01-01: x-idempotency-key or x-idempotency-header
Version indicator Not versioned in a header on the pages checked x-webhook-version (2023-08-01, 2025-01-01, 2026-01-01); payload shapes differ
Success response Any 2xx; non-2xx is a failure Return 200 (overview) or 2xx (payment webhooks page)
Response timeout 5 seconds, then marked timeout and resent Not stated on the pages checked
Retry policy Exponential backoff for 24 hours from event creation Default: up to 3 retries at 2, 10 and 30 minutes; configurable fixed, exponential or custom schedules up to 10 retries
Attempt indicator Not stated x-webhook-attempt
After repeated failure Webhook disabled after 24 hours of failures; email to Alert Email Address; re-enable from Dashboard Automatic disablement not stated
Ordering Not guaranteed (documented) Not stated
Manual resend Dashboard replay for recent unacknowledged events Batch Resend in Webhooks > Logs, windows up to 24 hours, payment webhooks only
Example payment events payment.authorized, payment.captured, payment.failed, order.paid PAYMENT_SUCCESS_WEBHOOK, PAYMENT_FAILED_WEBHOOK, PAYMENT_USER_DROPPED_WEBHOOK, PAYMENT_CHARGES_WEBHOOK

“Not stated” means the pages we checked do not document it, not that the provider lacks it.

How do you verify a Razorpay webhook signature?

Razorpay computes an HMAC-SHA256 hash of the raw request body using the webhook secret you set in the Dashboard. That secret is separate from your API key ID and key secret. You recompute the hash and compare it with X-Razorpay-Signature. Three rules matter in practice:

  1. Capture the raw bytes before any JSON middleware runs. Re-serialising a parsed object can change the bytes. Razorpay’s own Node.js snippet passes JSON.stringify(body) to validateWebhookSignature, which conflicts with its raw-body warning, so pass the unmodified body instead.
  2. Compare in constant time and reject on mismatch with a non-2xx response. Never “log and continue”.
  3. Plan secret rotation. Razorpay notes that retries of older requests after a secret change should be validated with the old secret. Accept both secrets for at least the 24-hour retry window. See our guide to key rotation without downtime.

The Node.js example below verifies the signature, records the event ID under a unique constraint, acknowledges quickly and queues slow work.

// Razorpay payment webhook receiver (Node.js 18+, Express 4)
// Illustrative: test in Razorpay Test mode before production use.
const express = require('express');
const crypto = require('crypto');
const { Pool } = require('pg');
const queue = require('./queue'); // your durable job queue
const db = new Pool();
const app = express();
// Secrets come from a secret manager, never from source code.
const SECRETS = [process.env.RZP_WEBHOOK_SECRET, process.env.RZP_WEBHOOK_SECRET_PREVIOUS]
  .filter(Boolean);
function signatureValid(rawBody, received) {
  if (!received) return false;
  const given = Buffer.from(received, 'utf8');
  return SECRETS.some((secret) => {
    const expected = Buffer.from(
      crypto.createHmac('sha256', secret).update(rawBody).digest('hex'), 'utf8');
    return expected.length === given.length && crypto.timingSafeEqual(expected, given);
  });
}
// express.raw keeps req.body as a Buffer: the exact bytes Razorpay signed.
app.post('/webhooks/razorpay', express.raw({ type: 'application/json' }), async (req, res) => {
  const eventId = req.get('x-razorpay-event-id');
  if (!signatureValid(req.body, req.get('x-razorpay-signature'))) {
    console.warn('rzp_webhook_invalid_signature', { eventId });
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString('utf8')); // parse only after verifying
  try {
    // Unique constraint on event_id makes de-duplication atomic.
    const result = await db.query(
      `INSERT INTO webhook_inbox (provider, event_id, event_type, entity_id, received_at, payload)
       VALUES ('razorpay', $1, $2, $3, now(), $4)
       ON CONFLICT (provider, event_id) DO NOTHING`,
      [eventId, event.event, event.payload?.payment?.entity?.id ?? null, event]);
    if (result.rowCount === 1) {
      await queue.enqueue('process-razorpay-event', { eventId }); // slow work happens later
    } else {
      console.info('rzp_webhook_duplicate', { eventId });
    }
    return res.status(200).send('ok'); // acknowledge well inside 5 seconds
  } catch (err) {
    console.error('rzp_webhook_store_failed', { eventId, err: err.message });
    return res.status(500).send('retry'); // non-2xx asks Razorpay to retry
  }
});
app.listen(3000);

Acknowledge only after the event is durably stored. If you return 200 and crash before saving, Razorpay will not retry. If the insert fails, returning 500 asks for a retry.

How do retries, timeouts and alerts work?

Razorpay treats any non-2xx response, or no response within 5 seconds, as a failure. It retries with exponential backoff for 24 hours from the event’s creation timestamp. If deliveries keep failing for 24 hours, the webhook is disabled and an email goes to the Alert Email Address set during webhook setup (or the account email if none was set). You fix the endpoint and re-enable the webhook from the Dashboard.

Your monitoring should fire long before that window closes. Useful signals:

  • rate of non-2xx responses and signature failures per hour;
  • age of the oldest unprocessed row in your inbox or queue;
  • orders still “pending” more than 15 minutes after payment creation;
  • the disablement email, routed to an on-call channel.

Cashfree’s default schedule is shorter (three retries at 2, 10 and 30 minutes), but you can configure fixed, exponential or custom schedules with up to 10 retries. Check which schedule each Cashfree endpoint uses, because a short default changes how quickly you must reconcile. Do not assume identical delivery guarantees.

How should you handle duplicate and out-of-order events?

Both providers deliver at least once, so a duplicate is normal. Separate three identifiers:

  • Delivery or event identifier (x-razorpay-event-id): stops the same notification being processed twice.
  • Payment ID (pay_…): one payment can produce several different events, such as authorised and captured.
  • Order ID (your order and Razorpay’s order_…): one order can have several payment attempts, some failed and one successful.

Event de-duplication is not enough. Fulfilment must be idempotent too: an order moves pending to paid to fulfilled once, never backwards, and only after amount, currency and order reference match your record.

Example sequence A: repeated notification

  1. 10:00:01 payment.captured, event E1, payment P1 for order O1. Stored; O1 moves to paid; shipment created.
  2. 10:00:09 Your 200 was lost in transit; Razorpay resends E1.
  3. Unique constraint rejects it; logged as duplicate; 200 returned. No second shipment.

Example sequence B: late and out-of-order events

  1. 10:02:00 payment.captured (E7) for P2 arrives first. O2 moves to paid.
  2. 10:02:04 payment.authorized (E6) for P2 arrives. New event ID, so stored, but O2 is already past authorised. No change.

Example sequence C: failure after success on the same order

  1. Payment P3 fails (payment.failed); the customer retries and P4 is captured.
  2. P3’s failure event arrives after P4’s capture. The handler sees O3 is paid by P4 and records the failure without cancelling.

When an event and your record disagree, fetch the payment from the Razorpay API and treat that as authoritative.

Where do logs fit, and what should you record?

Provider logs show whether an event was delivered and what response it got. Razorpay’s blog describes a short Dashboard view of recent deliveries and self-service replay for recent unacknowledged events, with request and entity caps. Cashfree documents Batch Resend under Webhooks > Logs for windows of up to 24 hours, for payment webhooks only. Neither shows whether your system fulfilled the order.

Your records should hold the minimum needed to investigate:

  • provider, event ID, event type, payment ID, provider order ID and your order ID;
  • event creation time (from the payload), received time, processed time and outcome;
  • HTTP response code returned and signature result (valid or invalid, never the signature value);
  • attempt number where the provider sends one (Cashfree’s x-webhook-attempt).

Exclude secrets, API keys, card or VPA details and unnecessary customer data. If you keep raw payloads, use a restricted store with short retention. Limit Dashboard access too; see payment gateway dashboard roles and access controls.

What should your outage recovery runbook include?

Use this checklist when your endpoint has failed or the webhook has been disabled.

  1. Confirm scope. Record outage start and end from monitoring and the provider’s delivery log.
  2. Restore the endpoint. Fix the cause and confirm a test event in Test mode returns 2xx within 5 seconds.
  3. Re-enable the webhook in the Razorpay Dashboard if it was disabled. Check the Alert Email Address is a monitored team address.
  4. Keep de-duplication on. Never clear the inbox table; retries and replays repeat processed events.
  5. Reconcile payment status. Fetch each still-pending order from the outage window via the provider API and update it through the same idempotent transitions.
  6. Replay safely. Use the provider’s resend or replay feature for the window if available. For Razorpay, note that replayed events may use the current webhook secret.
  7. Hold manual refunds until reconciliation finishes, to avoid the refund-and-ship scenario.
  8. Close and review. Record events received, duplicates, orders recovered and customer impact. Escalate provider issues through the documented route; our support and escalation comparison sets these out.

Which test cases should pass before go-live?

Test How to run it Expected result
Invalid signature Send a captured payload with one character changed, or signed with the wrong secret 400 returned; nothing stored; alert counter increments
Body mutation Route the request through JSON middleware before verification Verification fails, confirming your raw-body path is the only one used
Duplicate delivery Send the same event ID twice, then concurrently One inbox row, one fulfilment, both requests get 200
Out-of-order events Send payment.captured before payment.authorized Order ends as paid; no regression
Delayed event Deliver a failure event for an earlier attempt after a later capture Order stays paid
Slow handler Add a 6-second delay before responding Retry received and de-duplicated; then remove delay and confirm queue hand-off
Endpoint unavailable Return 503 for 30 minutes in Test mode Alerts fire; retries recover events; reconciliation finds no missing orders
Secret rotation Rotate the secret, then deliver an older retry Old secret still accepted during the overlap window

Razorpay needs a public URL for test webhooks and blacklists several tunnelling domains, so use a Test-mode staging host.

Why we recommend Razorpay for a payment-event recovery runbook

For a team building a documented recovery process, we recommend Razorpay when its documented workflow matches the team’s needs. Our criteria were:

  • Verification: a single HMAC-SHA256 scheme over the raw body, with SDK helpers in six languages and guidance on old-secret retries.
  • Event identity: a per-event header, x-razorpay-event-id, documented specifically for duplicate detection.
  • Bounded retries: a stated 5-second timeout and a 24-hour exponential retry window, which make alert thresholds easy to set.
  • Failure handling: documented disablement, an alert email and a Dashboard re-enable step that fit naturally into a runbook.
  • Honest constraints: Razorpay explicitly says delivery order is not guaranteed, so you design for it from day one.

These are practical implementation reasons. They are not evidence of better uptime, stronger security or capabilities Cashfree lacks.

When Cashfree may fit better

Cashfree may suit a team that wants to tune retry schedules per endpoint, with fixed, exponential or custom options of up to 10 retries. Its explicit webhook versioning, an attempt-number header and timestamp-bound signatures may also fit teams that manage payload changes carefully. If you already process Easy Split or other Cashfree products, a single provider’s event model can simplify operations; see our Route vs Easy Split comparison. Confirm the idempotency header name and signature construction for your webhook version first.

FAQs

1. Can I mark an order paid when the customer is redirected back to my site?

No. The redirect only tells you the browser returned, and it can be lost or forged. Show a confirmation-pending page and wait for a verified webhook or a server-side status check, which both Razorpay and Cashfree provide. Fulfil only when your durable order record has moved to paid after checking amount, currency and order reference against the provider’s authoritative state.

2. Why does my Razorpay signature check fail even with the correct secret?

The most common cause is body mutation. If a framework parses JSON before you verify, the re-serialised string may differ from the bytes Razorpay signed. Capture the raw body, for example with express.raw, and verify before parsing. Also check you are using the webhook secret, not the API key secret, that Test and Live secrets are not mixed, and that a rotation has not left older retries signed with the previous secret.

3. How long does Razorpay keep retrying a failed webhook?

Razorpay retries failed deliveries with exponential backoff for 24 hours from the event’s creation timestamp. A failure is any non-2xx response or no response within 5 seconds. If failures continue for 24 hours, the webhook is disabled and an email goes to the configured alert address. Re-enable it after fixing the endpoint, then reconcile pending orders through the payment APIs.

4. Does a duplicate webhook mean the customer was charged twice?

Not necessarily. Both providers use at-least-once delivery, so the same event can arrive more than once for a single payment. Check the event identifier first: a repeated x-razorpay-event-id is the same notification. Then check the payment ID. Two different payment IDs on one order can mean two genuine payment attempts, which needs a refund decision. Your handler should never ship or credit twice for one order.

5. What is the difference between an event ID, a payment ID and an order ID?

The event ID identifies one notification and is used to discard duplicate deliveries. The payment ID identifies a single payment attempt, which can generate several events such as authorised and captured. The order ID groups the attempts for one purchase. Store all three, de-duplicate on the event ID, and drive fulfilment from order state so that late events cannot trigger a second shipment.

6. Is IP allowlisting enough to secure a webhook endpoint?

No. Razorpay recommends allowlisting its webhook IPs, but treat this as a supplementary control. Allowlisting does not prove the payload is unaltered. Always verify the HMAC signature on the raw body, reject mismatches with a non-2xx response, and keep secrets in a secret manager. For Cashfree, also check the timestamp header that forms part of the signed content. Our webhook security checklist covers the wider set of controls.

Author

  • Gokul GS

    Gokul GS is the lead editor of paymentsecuritypros.com and writes its Indian payment gateway comparisons, covering fees, settlement, merchant support and dispute handling across Razorpay, Cashfree, PayU, Pine Labs and others.

GG

Gokul GS

Gokul GS is the lead editor of paymentsecuritypros.com and writes its Indian payment gateway comparisons, covering fees, settlement, merchant support and dispute handling across Razorpay, Cashfree, PayU, Pine Labs and others.

Leave a Reply

Your email address will not be published. Required fields are marked *