Idempotency🔗

There could be scenarios where your endpoint might receive the same webhook event multiple times. This is an expected behaviour based on the webhook design.

To handle duplicate webhook events:

1. You can identify the duplicate webhooks using the x-razorpay-event-id header. The value for this header is unique per event.
2. Check the value of x-razorpay-event-id in the webhook request header.
3. Verify if an event with the same header is processed at your end.

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 the request times out, it is considered a failure.

On failure, a webhook is re-tried at progressive intervals of time, defined in the exponential back-off policy, for 24 hours. If the failures continue for 24 hours, the webhook is disabled. You need to enable the webhook from the Razorpay Dashboard after fixing the errors at your end. Know more about enabling Webhooks.

Setup Webhooks🔗

Watch this video to see how to set up a webhook.

To set up webhooks:

1. Log into the Razorpay Dashboard and navigate to Settings → Webhooks.

2. Click the + Add New Webhook button.

   

3. In the Webhook Setup pop-up page:

   1. Enter the URL where you want to receive the webhook payload when an event is triggered. We recommended using an HTTPS URL. Handy Tips
      You can set up to 5 URLs to receive Webhook notifications. Webhooks can only be delivered to public URLs. If you attempt to save a localhost endpoint as part of a webhook setup, you will notice an error. Know more about testing Webhooks on an application running on 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. Know more about how to validate webhooks. Handy Tips
      
      • 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.
      • The webhoook secret does not need to be the merchant secret key provided by Razorpay.
   3. In the Alert Email field, enter the email address to which the notifications should be sent in case of webhook failure. You will receive webhook deactivation notifications to this email address.
   4. Select the required events from the list of Active Events.
   

4. Click Create Webhook.

5. After you set a webhook, it appears on the list of webhooks.
   

You can click Edit to make changes to the webhooks.

Validation🔗

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. We provide support for validating the signature is in all of our language SDKs.

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.

Check Token Status using Webhooks🔗

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

Check Registration Link Status using Webhooks🔗

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