API ReferenceIntegrationsKnowledge Base

RazorpayX - 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 to us 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 a webhook event's duplicity.

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 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 that has the reason for failure 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.

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