Idempotency#

Your server should be configured to handle or receive the same event details multiple times. In case you are receiving the same webhook event again, you should check for the same webhook event data and ignore it.

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 keep receiving failure responses consecutively for 24 hours, we disable the webhook. You will 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.

Use Cases#

There can be multiple usages of webhook events. Two of these are listed below.

Set Up Webhooks#

To setup webhook for various events:

1. Log into your Razorpay Dashboard and navigate to Settings → Webhooks.
2. Click Setup Webhook.
3. Enter the following details:
   1. Enter the Website URL where you want to receive the webhook payload when an event is triggered.
   2. Enter a Secret for the webhook endpoint. The Secret is used for validation purposes. Note:
      The secret that you enter here can be used to validate that the webhook is from Razorpay. This should not be exposed publicly.
   3. Select the required events from the list of Active Events .
4. Click Save to enable 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 which you need to validate at your end.

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.

Support for validating the signature is provided in all of our SDKs:

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

Copykey                = webhook_secret
message            = webhook_body
received_signature = webhook_signature

expected_signature = hmac('sha256', message, key)

if expected_signature != received_signature
    throw SecurityError
end

Edit and Deactivate Webhooks#

Once created, you can edit your webhook details like URL, Secret and Active Events. You can also deactivate your webhook by unselecting the Active checkbox.

Test Webhooks#

In case you want to test and check webhooks before you integrate it on your server, you can do so by using any of the free webhook testing websites. A simple Google search for test webhooks online returns multiple sites that you can use to test webhooks.

Below are steps to use one such site.

1. Open requestbin.com.
2. Click Create a Request and login using Google or GitHub to create a private bin.
   • In case you do not want a private bin and are okay using a public bin, you can uncheck the Private option and click Create a Request.
3. Copy the endpoint created for you.
4. Proceed to set up webhooks, but with the following changes:
   • Ensure you are using Test Mode on the Dashboard when testing webhooks.
   • Paste the the endpoint you copied in Step 3 in the Website URL field.

When you complete a test payment, and have enabled the appropriate webhook during setup, you will receive the webhook payload on your requestbin.com site.