Available in🇮🇳 India
Receive onboarding events from test accounts, verify their signatures and handle repeats, retries and late events before you go live.
Razorpay sends an event to your webhook URL when a product’s status changes. This includes a change your own call caused, such as submitting. Razorpay also sends an event when a product’s requirements change without a call from you, and when the sub-merchant withdraws your access. Events are signed, delivered at least once and retried with exponential backoff for up to 24 h. Test-mode accounts send to your test-mode subscription.
Start with the overview for test credentials and headers.
1. Test Mode Coverage
Test Mode Differences
Webhooks run in test mode as in live mode. Subscribe a test-mode URL and secret, then onboard test accounts. Each change sends its event within a few seconds. The table below lists how webhooks behave in each mode:What You Can Test
The table below lists the areas to test for webhooks:Endpoint Coverage in Test Mode
Webhooks have no endpoint to call. The table below lists each event and how to trigger it in test mode:2. Before You Begin
Prepare the following before you run the scenarios:- Subscribe a test-mode webhook URL and secret on the Partner Dashboard.
- Keep the test-mode webhook secret in your secrets manager. It is separate from the API secret.
The Event Your Endpoint Receives
Each event names what happened and carries only what changed: the account’sid and updated_at, and each changed part in full, such as the complete product with its status and requirements. Fetch the account for everything else. The event below is a test-mode activation.
Request
Return any
2xx within 5 sec.
Event Body
Event Body
Body
Verify the Signature
Compute the signature over the raw body, before JSON parsing, and compare it in constant time:Node.js
Events
The table below lists every event and what your integration should do:
Know more about onboarding webhooks.
3. Test Scenarios
Work through these scenarios in order. Each row gives the trigger and what to confirm on your endpoint.3.1 Scenarios
Live scenarios work in test mode today. Coming soon scenarios are not available in test mode yet. The table below lists 11 scenarios. All 11 are coming soon:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Verify the signature Coming soon | Any event | Compute HMAC-SHA256 of the raw body with your test-mode webhook secret. Compare it with X-Razorpay-Signature in constant time. |
| 2 | Reject a changed body Coming soon | An event with 1 byte changed | Replay a received event to your endpoint with 1 byte changed. Confirm your endpoint rejects it and processes nothing. |
| 3 | Ignore a repeat Coming soon | The same X-Razorpay-Event-Id twice | Replay a received event unchanged. Confirm your endpoint acknowledges the second and does not process it again. |
| 4 | Acknowledge quickly Coming soon | Any event | Return 2xx within 5 sec and process asynchronously. Razorpay retries a slower answer. |
| 5 | Events out of order Coming soon | under_review arriving after activated | Compare payload.account.updated_at, or fetch the account and use its current status. |
| 6 | A missed webhook Coming soon | Your endpoint returning HTTP 500 for an hour | Fail every delivery for an hour, then recover. Confirm the retries arrive and nothing is processed twice. Confirm a fetch catches up what you missed. |
| 7 | Activated Coming soon | account.product.activated | Onboard test business Individual A. Turn on payments for the shop. |
| 8 | Every other product status Coming soon | The outcome accounts 000000000002 to 000000000006 | Submit 1 account per value. Handle under_review, edd_pending, needs_clarification, rejected and suspended as in the events table. |
| 9 | Requirements changed Coming soon | Website https://curlec.com, or an outcome on a hosted test page | Send the website, or complete a link on its hosted test page. Re-render from the product in the payload, or fetch the account. |
| 10 | Access withdrawn Coming soon | Settlement account 000000000007 | Submit and confirm activated. About 60 sec later, receive account.consent.withdrawn. Stop calling the API for the account. Confirm later calls return 403 consent_withdrawn. |
| 11 | Test and live events apart Coming soon | mode in the event | Confirm test events carry mode: test. Route them away from live shops. |
3.2 Scenario Details
The details below expand the scenarios that need more than one step:1. Verify the Signature
1. Verify the Signature
How to test: Verify every event before parsing it, as in the snippet. Use HMAC-SHA256 of the raw body with the webhook secret, compared in constant time.Expected result: A valid event matches. A changed event does not (#2).Your integration should: Keep the webhook secret for each mode in your secrets manager. It is separate from the API secret.
6. A Missed Webhook
6. A Missed Webhook
How to test:
- Make your endpoint return HTTP 500 for an hour while you onboard a test account.
- Let it recover.
X-Razorpay-Event-Id once. Fetch the account to catch up after an outage.7. Activated
7. Activated
How to test: Onboard test business Individual A to activation.Expected result: 1 delivery, retried until you return
2xx or for up to 24 h. The body is the sample event above. payload.account has the account’s id, updated_at and the complete product, and nothing else.Your integration should: Act on event and product. Fetch the account before anything irreversible.10. Access Withdrawn
10. Access Withdrawn
How to test: Submit an account with settlement account
000000000007.Expected result: The product is activated. About 60 sec later, account.consent.withdrawn arrives with product: null and the account’s id and updated_at. Every later call for the account returns HTTP 403 with reason: consent_withdrawn.Your integration should: Stop syncing the account, and tell the sub-merchant how to reconnect.Live mode differs: The sub-merchant withdraws your app’s access from their Razorpay Dashboard.3.3 Errors to Handle
Every error returns the same object. Branch onerror.reason and error.field, because the description can change. The overview lists the errors every operation shares.
The table below lists the error tied to webhooks:
4. Common Integration Gaps
These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. The Test with column points to the scenario that proves you have handled each one. Delivery The table below lists the gaps in handling delivery:
Status
The table below lists the gaps in handling status: