Webhooks

Introduction#

Webhooks allow you to build or set up integrations which subscribe to certain events on Razorpay API. When one of those events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL.

You can set up a webhook from your dashboard and configure separate URLs for live mode and test mode. A test mode webhook will only receive events for your test transactions. In URLs, only port numbers 80 and 443 are currently allowed.

When setting up the webhook, you will be asked to specify a secret. Using this secret, you can validate that the webhook is from Razorpay. Entering the secret is optional but recommended. The secret should never be exposed anywhere publicly.

Idempotency#

Your server should be configured to handle or receive the same event details multiple times. In case you are receiving the same webhook event again, you should check for the same webhook event data and ignore it.

Deactivation#

All webhook responses must return a status code in the range 2XX within a window of 5 seconds. If we receive response codes other than this or if the request times out, it is considered a failure. On failure, a webhook is retried once every hour for 24 hours. If we keep receiving failure responses consecutively for 24 hours, we disable the webhook. You will then need to manually re-enable the webhook from the Dashboard after fixing the errors at your end.

Note: For every failure, we send out an email notification along with the reason and the error code received by us.

Available Events#

Following table describes the events for which webhooks are currently available:

payment.authorized: Triggered whenever a payment is authorized.
payment.captured: Triggered whenever a payment is successfully captured.
payment.failed: Triggered whenever a payment fails.
order.paid: Triggered when an order is successfully paid.
invoice.paid: Triggered when an invoice is successfully paid.
invoice.expired: Triggered when an invoice gets expired.
settlement.processed: Triggered when a transfer made to a linked account is settled with the parent merchant. (Available only for Razorpay Route.
payment.dispute.created: Triggered when a dispute is raised by the issuing bank of the customer against a payment.

You can view sample payloads of the above mentioned events here.

Use Cases#

There can be multiple usages of webhook events. Two of which are listed below:

Capturing Delayed Authorized Payments#

Capturing payments for which you did not receive a response on client side is perhaps the most important use case for payment.authorized event. Sometimes, the communication between the bank and Razorpay or between you and Razorpay may not take place. This could be due to slow network connection, or closing the window when payment is being processed. This could lead to a payment being marked as Failed on Razorpay Dashboard but changed to Authorized at a later time. You can use webhooks to get notified about payments that get authorized and analyse this data to decide whether or not to capture the payment.

Notifications on Failed Payments#

When a payment attempted by your customer fails, we receive the failed payment status from the bank. This payment gets recorded in our system as Failed. If you have enabled the webhook for the event payment.failed, you will receive a notification from us about the failed payment. You can then further analyse this payment and send out an email to your customer informing them about the same.