Webhooks allow you to build or set up integrations that subscribe to certain events on Razorpay APIs. When one of those events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL.
You can set up webhooks from your Dashboard and configure separate URLs for live mode and test mode.
A test mode webhook will only receive events for your test transactions.
In URLs, only port numbers 80 and 443 are currently allowed.
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.
To avoid an event being missed, Razorpay follows at-least-once delivery semantics. In this approach, if we do not receive a successful response from your server, we resend the Webhook.
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.
Check 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.
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 at progressive intervals of time, defined in the exponential backoff policy, for 24 hours. If the failures persist for 24 hours, the webhook is disabled. You will then need to re-enable the Webhook from the Dashboard after fixing the errors at your end.
Razorpay will send you an email notification when a webhook gets disabled due to multiple failures.
Enter the URL where you want to receive the webhook payload when an event is triggered. We recommended using an HTTPS URL.
Webhooks can only be delivered to public URLs. If you attempt to save a localhost endpoint as part of a webhook set-up, you will notice an error. Please refer to the test webhooks section for alternatives to localhost.
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. Learn more about Webhook Secret.
In the Alert Email field, enter the email address to which notifications must be sent in case of webhook failure.
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 that you need to validate at your end. Support for validating the signature is provided in all of our langauge SDKs.
Do not parse or cast the webhook request body.:
While generating 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.
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