API ReferenceIntegrationsKnowledge Base

Webhooks

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.

Idempotency#

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.

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 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.

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

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.
×