> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Tests

> Test Onboarding APIs webhooks in Test Mode, including signature, retry and product status scenarios.

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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) 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:

| Behaviour | Live mode | Test mode |
| - | - | - |
| Signature and delivery | Events are signed with your live-mode webhook secret and retried with exponential backoff for up to 24 h. | Test-mode events are signed with your test-mode secret and retried as in live mode. |
| Product status events | Each fires when a review, a check or the sub-merchant moves the product. | Each fires when the status of the test account changes. The outcome accounts force each one. |
| `account.requirements.updated` | Fires when a check settles after the response, or the sub-merchant completes a step at a link. | Fires when an `in_progress` check settles after the response, the website check included. Also fires when a step on a hosted test page completes and clears its requirement. |
| `account.consent.withdrawn` | The sub-merchant withdraws your app's access from their Razorpay Dashboard. | Settlement account `000000000007` withdraws access about 60 sec after activation. |

### What You Can Test

The table below lists the areas to test for webhooks:

| Area | What to test | In test mode |
| - | - | - |
| Signature and delivery | Verifying, acknowledging, repeats and retries | Available |
| Product status events | All 6 | Available |
| Requirements events | `account.requirements.updated` | Available |
| Consent withdrawal | `account.consent.withdrawn` | Available |

### 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:

| Event | How to trigger it in test mode | In test mode |
| - | - | - |
| `account.product.under_review` | Submit with settlement account `000000000002`, `000000000003` or `000000000005` | Available |
| `account.product.edd_pending` | Submit with settlement account `000000000004`, or with a PAN that has no Central KYC Records Registry (CKYC) record | Available |
| `account.product.needs_clarification` | Submit with settlement account `000000000003` | Available |
| `account.product.activated` | Onboard test business Individual A to activation | Available |
| `account.product.rejected` | Submit with settlement account `000000000002` | Available |
| `account.product.suspended` | Submit with settlement account `000000000006` | Available |
| `account.requirements.updated` | Send website `https://curlec.com`, or pick an outcome on a hosted test page | Available |
| `account.consent.withdrawn` | Submit with settlement account `000000000007` | Available |

## 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.

```http Request theme={null}
POST <your webhook URL>
X-Razorpay-Signature: 3f1c9a7e2b4d…
X-Razorpay-Event-Id: evt_Kq3Lm8Zp2RtV1x
Content-Type: application/json
```

The table below lists the headers on each event:

| Header | What it carries |
| - | - |
| `X-Razorpay-Signature` | Hash-based Message Authentication Code (HMAC) SHA-256 of the raw body, keyed with the webhook secret from the Partner Dashboard, as hex |
| `X-Razorpay-Event-Id` | The event's `id`, the same on every retry |

Return any `2xx` within 5 sec.

> [accordion] Event Body
>
> ```json Body theme={null}
> {
>   "id": "evt_Kq3Lm8Zp2RtV1x",
>   "entity": "event",
>   "event": "account.product.activated",
>   "mode": "test",
>   "account_id": "acc_TcdGEzmfKQzEl1",
>   "product": "payment_gateway",
>   "payload": {
>     "account": {
>       "id": "acc_TcdGEzmfKQzEl1",
>       "products": {
>         "payment_gateway": {
>           "type": "payment_gateway",
>           "status": "activated",
>           "status_reason": null,
>           "created_at": 1793164800,
>           "updated_at": 1793165101,
>           "requirements": [],
>           "terms_of_service_acceptance": {
>             "ip": "203.0.113.42",
>             "device_fingerprint_id": "df_9Hq4Lt2Vb5Ks8Zp",
>             "metadata": {},
>             "accepted_at": 1793165100
>           },
>           "payment_channels": {
>             "website": {
>               "primary": "https://curlec.com",
>               "additional": [],
>               "verification": {
>                 "status": "verified",
>                 "error_code": null,
>                 "error_description": null,
>                 "verified_at": 1793164935,
>                 "metadata": {},
>                 "created_at": 1793164930
>               }
>             },
>             "app_android": null,
>             "app_ios": null
>           }
>         }
>       },
>       "updated_at": 1793165101
>     }
>   },
>   "created_at": 1793165102
> }
> ```

### Verify the Signature

Compute the signature over the raw body, before JSON parsing, and compare it in constant time:

```javascript Node.js theme={null}
const crypto = require('crypto');
function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
// rawBody: the request body exactly as received, before JSON parsing
// signature: the X-Razorpay-Signature header
```

### Events

The table below lists every event and what your integration should do:

| Event | When | What your integration should do |
| - | - | - |
| `account.product.under_review` | A product was submitted, its video KYC call finished or it was resubmitted after a clarification. | Tell the sub-merchant. Lock the KYC details. |
| `account.product.edd_pending` | A submitted product needs video KYC. | Show the `create_video_kyc_link` link. |
| `account.product.needs_clarification` | A reviewer asked for more. | Fetch the account. Show the flagged points. |
| `account.product.activated` | A product was activated. | Turn on payments for the shop. |
| `account.product.rejected` | A product was rejected. | Tell the sub-merchant. Stop offering changes. |
| `account.product.suspended` | An activated product was suspended. `status_reason` says why. | Stop payments. Show the reason and ask for what `requirements` lists. |
| `account.requirements.updated` | Requirements changed without a call from you. An `in_progress` check settled after the response, or the sub-merchant completed a step at a link. | Re-render from the product in the payload, or fetch. |
| `account.consent.withdrawn` | The sub-merchant withdrew your access through Razorpay. | Stop calling the API for the account. |

Know more about [onboarding webhooks](https://razorpay.com/docs/webhooks/partners/onboarding-apis.md).

## 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:

<table>
  <colgroup>
    <col width="6%" />

    <col width="22%" />

    <col width="24%" />

    <col width="48%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger</th><th>What to confirm</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Verify the signature Coming soon</td><td>Any event</td><td>Compute HMAC-SHA256 of the raw body with your test-mode webhook secret. Compare it with `X-Razorpay-Signature` in constant time.</td></tr>
    <tr><td>2</td><td>Reject a changed body Coming soon</td><td>An event with 1 byte changed</td><td>Replay a received event to your endpoint with 1 byte changed. Confirm your endpoint rejects it and processes nothing.</td></tr>
    <tr><td>3</td><td>Ignore a repeat Coming soon</td><td>The same `X-Razorpay-Event-Id` twice</td><td>Replay a received event unchanged. Confirm your endpoint acknowledges the second and does not process it again.</td></tr>
    <tr><td>4</td><td>Acknowledge quickly Coming soon</td><td>Any event</td><td>Return `2xx` within 5 sec and process asynchronously. Razorpay retries a slower answer.</td></tr>
    <tr><td>5</td><td>Events out of order Coming soon</td><td>`under_review` arriving after `activated`</td><td>Compare `payload.account.updated_at`, or fetch the account and use its current status.</td></tr>
    <tr><td>6</td><td>A missed webhook Coming soon</td><td>Your endpoint returning HTTP 500 for an hour</td><td>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.</td></tr>
    <tr><td>7</td><td>Activated Coming soon</td><td>`account.product.activated`</td><td>Onboard test business Individual A. Turn on payments for the shop.</td></tr>
    <tr><td>8</td><td>Every other product status Coming soon</td><td>The outcome accounts `000000000002` to `000000000006`</td><td>Submit 1 account per value. Handle `under_review`, `edd_pending`, `needs_clarification`, `rejected` and `suspended` as in the [events table](#events).</td></tr>
    <tr><td>9</td><td>Requirements changed Coming soon</td><td>Website `https://curlec.com`, or an outcome on a hosted test page</td><td>Send the website, or complete a link on its hosted test page. Re-render from the product in the payload, or fetch the account.</td></tr>
    <tr><td>10</td><td>Access withdrawn Coming soon</td><td>Settlement account `000000000007`</td><td>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`.</td></tr>
    <tr><td>11</td><td>Test and live events apart Coming soon</td><td>`mode` in the event</td><td>Confirm test events carry `mode: test`. Route them away from live shops.</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

The details below expand the scenarios that need more than one step:

> [accordion] 1. Verify the Signature
>
> **How to test:** Verify every event before parsing it, as in the [snippet](#verify-the-signature). 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.

> [accordion] 6. A Missed Webhook
>
> **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.

> [accordion] 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.

> [accordion] 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 on `error.reason` and `error.field`, because the description can change. The [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) lists the errors every operation shares.

The table below lists the error tied to webhooks:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| Any call after `account.consent.withdrawn` | 403 | `consent_withdrawn` | Not applicable |

## 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:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Parsing before verifying | A forged event changes an account's state in your system. | Verify the raw body first. | #1, #2 |
| Processing a repeat | A shop gets notified twice, or a status flips back. | Store `X-Razorpay-Event-Id` and skip repeats. | #3 |
| Slow acknowledgement | Events time out and Razorpay retries them, piling up duplicates. | Acknowledge in under 5 sec and queue the work. | #4 |

**Status**

The table below lists the gaps in handling status:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Trusting the last event received | An older event arrives late and overwrites a newer status. | Compare `updated_at`, or fetch before acting. | #5 |
| Reading the payload as the whole account | Fields that did not change are missing, and your copy of the account loses them. | Merge only what the payload carries, or fetch. | #7 |

## 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:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Webhooks and fetch together | Act on the event. Fetch when one is late or out of order. | Every status on this page. | #5, #6 | [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md) |
| The payload is what changed | Each event carries the changed parts in full, not the whole account. | The product is complete, and the rest is absent. | #7 | Not applicable |

### Related Information

* [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration)
* [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)
* [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md)
* [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)
* [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md)
* [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md)
* [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
* [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md)
* [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md)
* [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md)
