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.
Capturing payments for which you did not receive a response on the client-side is perhaps the most important use case for the payment.authorized event.
Sometimes, the communication between the bank and Razorpay or between you and Razorpay may not take place. This could be because of a slow network connection or your customer closing the window while the payment is being processed. This could lead to a payment being marked as Failed on the Razorpay Dashboard, but changed to Authorized at a later time.
You can use webhooks to get notified about payments that get authorized and analyze this data to decide whether or not to capture the payment.
When a payment attempted by your customer fails, we receive the failed payment status from the bank. This payment gets recorded in our system as Failed.
If you have enabled the payment.failed webhook, you will receive a notification from us about the failed payment. You can then further analyze this payment and notify your customer about the failure.
In order to avoid an event being missed, Razorpay follows at-least-once delivery semantics. Therefore, if we have not received a successful response from your server, the Webhook is resent. 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 as timeout and it is assumed that the Webhook has not been processed and therefore sent again. Hence, your server should be configured to handle or receive the same event details multiple times.
If you were to receive the same Webhook event again, you should check for duplicates using the header_value of the header_key parameter in the request payload.
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.
Note:
For every failure, Razorpay will send an email with the reason and the error code received by us.
Ideally, you should receive webhooks in the order in which the events occur. For example, in the case of a payment, webhooks should be fired in the below order:
payment.authorized
payment.captured
However, this is not guaranteed. You should configure your Webhook URL to not expect delivery of these events in this order and handle such scenarios.
Enter the Website URL where you want to receive the webhook payload when an event is triggered.
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. Do not expose the secret publicly.
Select the required events from the list of Active Events .
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.
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
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.
In case you want to test webhooks and check the payload, 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.
