About Webhooks

Check the various notifications (webhooks, emails and SMS) available to you when using RazorpayX.


Webhooks let you 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.

Handy Tips
It is important to validate and test webhooks before using them. Refer Validate and Test Webhooks for more information.

Available Events🔗

Listed below are the various webhooks events available in RazorpayX. The payload remains the same irrespective of the fund_account_type to which payout was made. The payload is the same whether the payout was made to a bank account, VPA or card.

The table below lists the webhook events available for RazorpayX Payouts.

Webhook Event

Applicable For

Description

payout.pending

all payouts

Triggered whenever a payout moves to the pending state. The payout remains in this state till you approve or reject it.

payout.rejected

all payouts

Triggered whenever a payout moves to the rejected state. The payout was rejected by someone from your team.

payout.queued

all payouts

  • Triggered whenever a payout moves to the queued state. Payout goes to queued state when you do not have sufficient funds to process it or when the beneficiary bank/NPCI/partner bank is down. This event is applicable only for Virtual account.

  • You will receive the reason for the payout to be in the queued state as part of the status_details object.

payout.initiated

all payouts

Triggered when the payout moves to the processing state when the payout is created or from the queued state when sufficient funds are available to process the payout.

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

all payouts

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

all payouts

Triggered when a payout is failed because the beneficiary bank OR NPCI OR processing partner bank is down. If the beneficiary bank/partner banks/NPCI does not recover within the stipulated SLA, a FAILED event will be sent with the respective reason. Handy Tips
It is mandatory to subscribe to the payout.failed event if you are using RazorpayX APIs.

The table below lists the webhook events available for RazorpayX transactions.

Webhook Events

Description

transaction.created

Triggered whenever you:

  • Make a Payout (virtual account or current account).
  • Add funds to your RazorpayX account (virtual account or current account).
  • Perform any kind of transaction (ATM transaction, cash withdrawal, netbanking transfer, encashed cheque) on your current account.
  • When your webhook secret is set, Razorpay uses it to create a hash signature with each payload. This hash signature is passed 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.

    X-Razorpay-Signature
    The hash signature is calculated using HMAC with SHA256 algorithm, 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

    Order of Events🔗

    For example for payouts, you should receive webhooks in the following order:

    1. payout.pending (if you have Approval Workflow enabled on your account)
    2. payout.queued (in case your business account does not have sufficient balance to process the payout)
    3. payout.initiated
    4. payout.processed or payout.reversed

    The above order may not be followed at all times. You should configure your webhook URL to not expect delivery of these events in this order and handle such scenarios.

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

    Setup Webhooks🔗

    Watch this video to set up webhooks in RazorpayX.

    Handy Tips

    It is important to validate and test webhooks before you start using them. To test webhooks, refer Validate and Test Webhooks.

    To set up webhooks:

    1. Log in to the RazorpayX Dashboard, and navigate to My Account & SettingsDeveloper Controls. Click Add Webhooks if you are setting up a webhook for the first time or Edit Webhook to edit a previously saved webhook.
    2. Enter the Webhook URL where you want to receive the webhook payload when an event is triggered. Handy Tips
    3. Enter a Secret for the webhook endpoint. This is an optional field and is used for validation. Secret for Webhooks
      • When setting up the Webhooks, 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.
      • The webhook secret does not need to be the merchant secret key provided by Razorpay.
    4. Select the events you want to subscribe from the list of Active Events.
    5. Click SAVE to enable the webhook.

    To edit webhooks: After you set the webhooks, you can click Edit to make changes to a webhook.

    ×