A payment gateway webhook is an HTTP notification sent from the gateway to your backend when a payment-related event occurs, such as a payment being authorised, captured, failed or refunded.<\/p>\n
Picture a hypothetical INR 2,499 order. The customer’s payment succeeds, but your merchant endpoint is restarting behind a bad deploy. The money moved. Your fulfilment system has no record of it. Minutes later the notification arrives twice, and your signature check rejects both because a JSON middleware rewrote the body first.<\/p>\n
That is the everyday shape of the problem: missing updates, repeated notifications and signature mismatches leaving order, refund and subscription records inconsistent. It usually surfaces during a checkout launch, an endpoint incident or a gateway integration review.<\/p>\n
The engineering question is specific. How do we verify a webhook, recover a missed event and ensure the same payment does not trigger fulfilment twice? Retrying delivery can itself produce duplicates, so the application needs durable receipt, deduplication and state checks. This guide sets out the evaluation criteria, then shows how Razorpay documents signatures, retries, logs, recovery and operation-specific idempotency.<\/p>\n
X-Razorpay-Signature<\/code> with an HMAC-SHA256 digest of the original request bytes, using your configured webhook secret. Register raw-body handling before JSON middleware. Reject altered payloads and malformed signatures; keep webhook secrets separate from API credentials and scope rotation to the delivery route.<\/li>\n- Delivery logs and application logs answer different questions.<\/strong> The India FAQ documents Dashboard logs for deliveries from the last three hours, including request and response headers. Owner, Pseudo Owner and R&D roles can view them. Your own durable inbox and worker logs establish whether the intended business action actually completed.<\/li>\n
- Missed events can be replayed within the documented limits.<\/strong> India self-service replay covers unacknowledged events up to seven days old, with up to five replay requests per 24 hours and 500 entity IDs per specific-events request. Acknowledged events are excluded. Selected disabled URLs are enabled automatically, and replayed events use the current webhook secret.<\/li>\n
- Duplicate prevention requires event-level and business-level checks.<\/strong> Atomically deduplicate
x-razorpay-event-id<\/code> within the relevant integration context, then enforce a separate business-operation constraint. Acknowledge only after durable receipt and process slower work asynchronously. Repeated or out-of-order notifications must not fulfil an order twice or move a captured payment back to an authorised state.<\/li>\n- Razorpay supports idempotent retries for specific API operations.<\/strong> Use
X-Payout-Idempotency<\/code> for supported payout operations, X-Refund-Idempotency<\/code> for Normal and Instant Refunds, and X-Transfer-Idempotency<\/code> for direct transfers. Reuse the same key and identical request for the same supported operation. These endpoint-specific contracts do not establish a universal idempotency header for every customer payment API.<\/li>\n<\/ul>\n<\/div>\nWhat Makes a Payment Gateway Webhook Reliable?<\/h2>\n
Evaluate payment gateway webhooks by how they authenticate events, retry failed deliveries, expose delivery history and recover missed notifications. Then check how your application handles duplicate and out-of-order events. Razorpay documents these controls, but dependable fulfilment also requires durable event storage, idempotent processing and payment-status reconciliation inside the merchant application.<\/p>\n
Compare Webhook Authentication, Delivery and Recovery Controls<\/h3>\n\n