API ReferenceIntegrationsKnowledge Base

Webhooks

Webhooks allow you to build or set up integrations that subscribe to certain events on Razorpay APIs. 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 webhooks 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 publicly.

Idempotency#

To avoid an event being missed, Razorpay follows at-least-once delivery semantics. In this approach, if we do not receive a successful response from your server, we resend the Webhook.

There could be situations where your server accepts the event but fails to return a response in 5 seconds. In such cases, the session is marked timeout. It is assumed that the Webhook has not been processed and is sent again. Ensure your server is configured to handle or receive the same event details multiple times.

Check the value of x-razorpay-event-id in the webhook request header. The value for this header is unique per event and can help you determine the duplicity of a webhook event.

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 at progressive intervals of time, defined in the exponential backoff policy, for 24 hours. If the failures persist for 24 hours, the webhook is disabled. You will then need to re-enable the Webhook from the Dashboard after fixing the errors at your end.

Note:
Razorpay will send you an email notification when a webhook gets disabled due to multiple failures.

Setup Webhooks#

You can set up multiple URLs to receive webhook notifications.

To setup webhooks:

  1. Log into your Razorpay Dashboard and navigate to SettingsWebhooks.
  2. Click + Add New Webhook.
  3. In the Webhook Setup modal:
    1. Enter the URL where you want to receive the webhook payload when an event is triggered. We recommended using an HTTPS URL. Note:
      Webhooks can only be delivered to public URLs. If you attempt to save a localhost endpoint as part of a webhook set-up, you will notice an error. Please refer to the test webhooks section for alternatives to localhost.
    2. Enter a Secret for the webhook endpoint. The secret is used to validate that the webhook is from Razorpay. Do not expose the secret publicly. Learn more about Webhook Secret.
    3. In the Alert Email field, enter the email address to which notifications must be sent in case of webhook failure.
    4. Select the required events from the list of Active Events. Sample payloads for all events are available.
  4. Click Create Webhook.

Once created, it appears on the list of webhooks:

Watch the short animation below for more details.

Validation#

When your webhook secret is set, Razorpay uses it to create a hash signature with each payload. This hash signature is passed along with each request under the X-Razorpay-Signature header that you need to validate at your end. Support for validating the signature is provided in all of our langauge SDKs.

Do not parse or cast the webhook request body.:
While generating signature at your end, ensure that the webhook body passed as an argument is the raw webhook request body. Do not parse or cast the webhook request body.

X-Razorpay-Signature
The hash signature is calculated using HMAC with SHA256 algorithm; with your webhook secret set as the key and the webhook request body as the message.

You can also validate the webhook signature yourself using an HMAC as shown below:

Copykey = webhook_secret message = webhook_body // raw webhook request body received_signature = webhook_signature expected_signature = hmac('sha256', message, key) if expected_signature != received_signature throw SecurityError end

Check Payment Status using Webhooks#

You can use these webhooks to check the status of the authorization payment and subsequent payments.

Webhook Event

Description

payment.authorized

Indicates the payment has been authorized. A payment is authorized when the customer’s payment details are successfully authenticated by the bank.

payment.captured

Indicates when the payment has been captured.

order.paid

Indicates the payment has been captured.

Payment.failed

Indicates that the payment has failed. If the payment fails, you need to create an authorization transaction again.

Payment Authorized#

Indicates the payment has been authorized. A payment is authorized when the customer’s payment details are successfully authenticated by the bank.

Payment Captured#

Indicates the payment has been captured.

Order Paid#

Indicates the payment has been captured.

Payment Failed#

This webhook indicates that the payment has failed. If the payment fails, you need to create an authorization transaction again.

Check Token Status using Webhooks#

You can use the below webhooks to check the status of the token.

Webhook Event

Applicable Methods

Description

token.confirmed

●Emandate
● Card
● Paper NACH
● UPI

Indicates that the bank has completed the mandate registration. Once confirmed, you can create subsequent payments as per your business needs.

token.rejected

●Emandate
● Card
● Paper NACH
● UPI

Indicates that the is rejected. If rejected, you need to create the authorization transaction again.

token.cancelled

UPI

Indicated the token has been cancelled.

token.paused

UPI

Indicated the token has been paused by your customer.

token.resumed

UPI

Indicated the token has been unpaused by your customer.

Token Confirmed#

Indicates that the bank has completed the mandate registration. Once confirmed, you can create subsequent payments as per your business needs.

Available for tokens authorized using the following methods:

  • Emandate
  • Card
  • Paper NACH
  • UPI

Token Rejected#

Indicates that the is rejected. If rejected, you need to create the authorization transaction again.

Available for tokens authorized using the following methods:

  • Emandate
  • Card
  • Paper NACH
  • UPI

Token Cancelled#

Indicated the token has been cancelled.

Token Paused#

Indicated the token has been paused by your customer.

Available only for tokens authorized via UPI.

Token Resumed#

Indicated the token has been unpaused by your customer.

Available only for tokens authorized via UPI.

Check Registration Link Status using Webhooks#

You can use these webhooks to check the status of the registration link.

Webhook Event

Description

invoice.paid

Indicates that a registration link is successfully paid.

invoice.expired

Indicates that a registration link has expired.

Invoice Paid#

Indicates that a registration link is successfully paid.

Invoice Expired#

Indicates that a registration link has expired.

×