Webhooks

Validate Test

Validate and Test Webhooks

Validate and test the webhook before you start using them. Understand Idempotency and the importance of the order of Webhook Events.

You need to validate and test the webhook before starting using them. It is also important to understand idempotency and the importance of the order of Webhook Events.

Test Webhooks🔗

You can test the webhooks to verify payloads or check if your webhook integration is working. Test events get triggered on a transaction done in the Test mode. As the payload structure remains the same in the Live and Test modes, you can rely on your stage testing.

You can test webhooks:

Using Request Interceptor Tools🔗

There are many free webhook testing tools available online. A simple Google search for test webhooks online returns multiple sites that you can use to test webhooks. For example, requestbin.com.

To test webhooks:

  1. Open requestbin.com.
  2. Click Create Request Bin and log in using Google or GitHub to create a private bin. Alternatively, you can opt for a public bin.
  3. Copy the endpoint created for you.
  4. Proceed to set up webhooks, but with the following changes:
    1. Ensure you are using Test mode on the Razorpay Dashboard.
    2. Paste the endpoint you copied in the previous step in the Website URL field.

If you have enabled the appropriate webhook event during setup, you will receive the corresponding webhook payload on your requestbin.com site.

Application Running on Localhost🔗

You cannot use localhost directly to receive webhook events as webhook delivery requires a public URL. You can handle this by creating a tunnel to your localhost using tools such as ngrok or localtunnel.

You can refer to the ngrok documentation to get started. Use the URL endpoint generated by these tools in the webhook URL while setting up your webhooks.

Application Running on Your Staging Environment🔗

You can test your webhook integration in the staging environment before taking it live. You should set up webhooks in the Test mode. You can configure your staging host endpoint in test mode and receive test events on it.

Validate Webhooks🔗

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.

Handy Tips
If you have changed your webhook secret, remember to use the old secret for webhook signature validation while retrying older requests. Using the new secret will lead to a signature mismatch.

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; 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

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.

Order of Webhooks🔗

Ideally, you should receive a webhook in the order in which the webhook events occur. However, you may not always receive the webhooks in the order.

Example - Payments🔗

For example, in the case of a payment, you should receive webhooks in the following order:

  1. payment.authorized
  2. payment.captured

The above order may not be followed at all times. You should configure your webhook URL to not expect delivery of these events in this order and handle such scenarios.

Watch Out!
Make sure you select the above mentioned webhooks correctly to receive the webhook events in the correct order.

Example - RazorpayX🔗

For example for payouts, you should receive webhooks in the following order:

  1. payout.pending (if you have Approval Workflow enabled on your account)
  2. payout.queued (in case your business account does not have sufficient balance to process the payout)
  3. payout.initiated
  4. payout.processed or payout.reversed

The above order may not be followed at all times. You should configure your webhook URL to not expect delivery of these events in this order and handle such scenarios.

The processed and reversed states are the last states for a payout. Their corresponding webhooks payout.processed or payout.reversed indicate this state change. Any webhook received after these should be ignored.

×

ON THIS PAGE