Skip to main content
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’s id 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
The table below lists the headers on each event: Return any 2xx within 5 sec.
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:
#ScenarioTriggerWhat to confirm
1Verify the signature Coming soonAny eventCompute HMAC-SHA256 of the raw body with your test-mode webhook secret. Compare it with X-Razorpay-Signature in constant time.
2Reject a changed body Coming soonAn event with 1 byte changedReplay a received event to your endpoint with 1 byte changed. Confirm your endpoint rejects it and processes nothing.
3Ignore a repeat Coming soonThe same X-Razorpay-Event-Id twiceReplay a received event unchanged. Confirm your endpoint acknowledges the second and does not process it again.
4Acknowledge quickly Coming soonAny eventReturn 2xx within 5 sec and process asynchronously. Razorpay retries a slower answer.
5Events out of order Coming soonunder_review arriving after activatedCompare payload.account.updated_at, or fetch the account and use its current status.
6A missed webhook Coming soonYour endpoint returning HTTP 500 for an hourFail every delivery for an hour, then recover. Confirm the retries arrive and nothing is processed twice. Confirm a fetch catches up what you missed.
7Activated Coming soonaccount.product.activatedOnboard test business Individual A. Turn on payments for the shop.
8Every other product status Coming soonThe outcome accounts 000000000002 to 000000000006Submit 1 account per value. Handle under_review, edd_pending, needs_clarification, rejected and suspended as in the events table.
9Requirements changed Coming soonWebsite https://curlec.com, or an outcome on a hosted test pageSend the website, or complete a link on its hosted test page. Re-render from the product in the payload, or fetch the account.
10Access withdrawn Coming soonSettlement account 000000000007Submit 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.
11Test and live events apart Coming soonmode in the eventConfirm 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:
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.
How to test:
  1. Make your endpoint return HTTP 500 for an hour while you onboard a test account.
  2. Let it recover.
Expected result: Razorpay retries each event with exponential backoff for up to 24 h. An event still failing after that is not sent again.Your integration should: Process each X-Razorpay-Event-Id once. Fetch the account to catch up after an outage.
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.
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 on error.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:

5. Best Integration Practices

These practices apply to every onboarding integration. The On this page column says what each one means here. The table below lists the practices for webhooks:
Last modified on November 18, 2026