Razorpay’s guidance urges merchants to treat payment webhooks as unreliable signals requiring verification, durable storage, replay and duplicate-safe processing rather than as proof that a transaction is complete.
Payment gateways increasingly depend on webhooks to keep merchants’ systems in step with payment events, but the plumbing is only as dependable as the application that receives them. Razorpay’s guide on webhook handling in India frames the core problem plainly: payments may be authorised, captured, refunded or failed while the merchant’s backend is temporarily unavailable, and the real risk is not just a missed message but an inconsistent record that can lead to duplicate fulfilment or broken subscription logic. The guide argues that merchants should treat webhooks as one part of a broader recovery design, not as a guarantee that a payment has been fully processed. According to Razorpay, that means building for authentication, retries, logs, replay and duplicate prevention rather than assuming a single successful delivery will solve everything.
The first line of defence is authenticity. Razorpay says webhook verification relies on an HMAC-SHA256 signature check against the raw request body, using the configured webhook secret and the X-Razorpay-Signature header. The company warns against passing an already parsed or reserialised JSON body into the verification step, because even a small change in formatting can invalidate the signature. That advice aligns with broader webhook guidance from other payment platforms, which stress that handlers should preserve the original payload bytes and reject anything that cannot be verified exactly as received.
Delivery behaviour matters just as much as cryptography. Razorpay documents a five-second response window and says failed deliveries are retried using an exponential-backoff pattern for up to 24 hours from event creation. If failures continue, the webhook is disabled and an alert is sent. Similar retry principles appear in webhook documentation from Glamx, Paymos and Payment Enablement, all of which describe retries after non-2xx responses, timeouts or connection errors while warning developers not to rely on any one retry schedule as permanent. The practical lesson is the same across providers: applications need durable event storage, quick acknowledgement and asynchronous processing, because a webhook may be delivered more than once and may arrive after the underlying payment state has already changed.
Razorpay also distinguishes clearly between delivery logs and application logs. Its India FAQ says Dashboard logs show webhook deliveries from the last three hours and include request and response headers, with access available to Owner, Pseudo Owner and R&D roles. That is useful for tracing transport-level failures, but it does not replace a merchant’s own records of whether an order was fulfilled, a refund was booked or a subscription was updated. The guide recommends pairing gateway logs with internal inbox records and worker logs so teams can tell the difference between a notification that arrived successfully and a business action that was actually completed.
Recovery is another major part of the picture. Razorpay says unacknowledged events can be replayed in India through self-service tools for events up to seven days old, subject to limits on request frequency and the number of entity IDs included in a request. Acknowledged events are excluded, and selected disabled URLs are re-enabled automatically during replay. The guide also notes that replayed events use the current webhook secret, which makes secret management and rotation part of the recovery plan rather than an afterthought. For older events, the documentation points merchants towards support-assisted routes, making clear that recovery windows and eligibility depend on the specific process being used.
The final safeguard is idempotency, both at the event layer and the business layer. Razorpay’s guidance says merchants should deduplicate by event ID, store verified events atomically and ensure that repeated or out-of-order notifications cannot trigger the same order twice. That is especially important because one payment can generate more than one event, and those events do not always arrive in sequence. The company also documents separate idempotency headers for certain outbound operations, including payouts, refunds and direct transfers, showing that retry safety is operation-specific rather than universal. In practice, the safest implementation combines signature verification, durable receipt, controlled retries and state-aware processing so that a lost acknowledgement does not become a lost payment, or a duplicate webhook, a duplicate sale.
Disclaimer: This article is intended to inform and educate, not to recommend or endorse any financial product, investment or strategy. Please consider your own financial circumstances and seek professional advice where appropriate before making financial decisions.
