API ReferenceIntegrationsKnowledge Base


Webhooks allow you to build or set up integrations that subscribe to certain events on RazorpayX API. When one of these 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. In URLs, currently, only port numbers 80 and 443 are allowed.

When setting up the webhook, we recommend you to enter a secret. Using this secret, you can validate that the webhook is from Razorpay. The secret should never be exposed anywhere publicly.


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

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.

You can identify duplicate events by checking 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.


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 receive failure responses consecutively for 24 hours, we disable the webhook. You then need to manually re-enable the webhook from the Dashboard after fixing the errors at your end.

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

Setup Webhooks#

To set up webhooks:

  1. Log into your RazorpayX Dashboard and navigate to My Account & SettingsDeveloper Controls → click Add Webhooks.
  2. Enter the Webhook URL where you want to receive the webhook payload when an event is triggered. Note:
    This Webhook URL can be different from your Razorpay PG Webhook URL.
  3. Enter a Secret for the webhook endpoint. This is an optional field and is used for validation purposes. Note:
    Do not expose your webhook secret publicly.
  4. Select the events to which you want to subscribe from the list of Active Events.
  5. Click Add Endpoint to enable the webhook.

Watch the short animation below for more details.

Once created, you can edit a webhook. Click Edit to edit the webhook.


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 our language SDKs.

Do not parse or cast the webhook request body:
While generating the 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.

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

Available Events#

Currently, webhooks are available for the following events:

payout.pending all payouts
Triggered whenever a payout moves to the pending state. That is, the payout needs to be approved by you.
payout.rejected all payouts
Triggered whenever a payout moves to the rejected state. That is, the payout was rejected by someone from your team.
payout.queued all payouts
Triggered whenever a payout moves to the queued state, either upon creation or from the pending state.
payout.initiated all payouts
Triggered when the payout moves to the processing state, either upon creation or from the queued state.
payout.processed all payouts
Triggered when a payout moves to the processed state. This happens when the payout is processed by the contact's bank.
payout.updatedall payouts
This webhook is triggered whenever there is a change in the payout entity. For example, when we receive the UTR for the payout from the bank. For NEFT transactions, this webhook is generally fired within 90 seconds. For IMPS and UPI transactions, this webhook is generally fired immediately.
payout.reversed all payouts
Triggered whenever a payout fails and the amount is returned to your business account.
payout.failed current account payouts
This webhook event is available only when a payout is made using your current account balance. This event is triggered when a payout is failed by our current account partner bank.
transaction.created transactions
Triggered whenever you make:
  • A Payout (virtual account or current account).
  • Add funds to your RazorpayX account (virtual account or current account).
  • Any kind of transaction (ATM transaction, cash withdrawal, netbanking transfer, encashed cheque) on your current account.

Order of Events#

Ideally, you should receive webhooks in the following order:

However, this is not guaranteed. You should configure your Webhook URL to not expect delivery of these events in this order and handle such scenarios.

processed and reversed are terminal states for a payout. Their corresponding webhooks payout.processed or payout.reversed indicate this state change. Any webhook received after these should be ignored.

Sample Payloads#

Below are sample payloads for the various webhook events. The payload remains the same irrespective of the fund_account_type to which payout was made.

That is, the payload is the same whether the payout was made to a bank account, vpa or card.