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

# 4. Subscribe to Webhooks

> Use Razorpay's Webhooks to track a payment method instrument from onboarding to activation, and to know when Razorpay or a bank needs more from the sub-merchant.

Available in
🇮🇳 India

Banks, providers and Razorpay move an instrument through onboarding over days. Razorpay tells your platform when an instrument changes, so you do not have to poll. Events are delivered the same way as the [Onboarding APIs webhooks](https://razorpay.com/docs/webhooks/partners/onboarding-apis.md), to the same webhook URL.

Every event carries the current state of one instrument, as the instrument object the [fetch](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/fetch-and-enable.md) response returns. One handler serves every event: verify, drop repeats, replace the instrument you hold and re-render. Fetching its payment method is always the source of truth.

## 4.1 Subscribe to the Webhook

Subscribe on the Partner Dashboard, once per mode, with an https URL, a secret and the events to receive.

| Event | When it fires | What it carries |
| - | - | - |
| `account.payment_methods.updated` | An instrument's status changed, for example to `activated`, `needs_clarification` or `rejected`. It fires on every status change, including one your own call caused. | The instrument that changed, as the fetch response returns it, with its `requirements`. |
| `account.payment_methods.requirements.updated` | Requirements changed without a call from your platform, for example after a check that runs later. | The instrument whose requirements changed, with its `requirements` as they now stand. It is a new event, delivered the same way as the Onboarding APIs events. |

## 4.2 Event Object

| Field | Type | Description |
| - | - | - |
| `id` | string | `evt_` followed by 14 letters or digits. It is the same value as the `X-Razorpay-Event-Id` header. Process each id once. |
| `entity` | string | `event`. |
| `event` | string | `account.payment_methods.updated` or `account.payment_methods.requirements.updated`. |
| `mode` | string | `live`, the mode of the subscription. |
| `account_id` | string | The account, `acc_`-prefixed. |
| `product` | string | `payment_gateway`. |
| `payload` | object | One key, `instrument`. |
| `payload.instrument` | object | The instrument the event is about, as the fetch response returns it: `instrument`, `name`, `logo_url`, `status`, `status_reason`, `enabled`, `requirements` (what is still due) and `updated_at`. Its payment method is the first segment of `instrument`. |
| `created_at` | integer | When the event was created, as a Unix timestamp in seconds. Order events about one instrument by it. |

## 4.3 Status Change Event

SBI credit-card EMI is activated by the bank. It was enabled before, so customers can pay with it as soon as it is activated.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Qm4Xr8Lt2Vb6Ns",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "emi/credit_card/banks/sbin",
      "name": "SBI credit-card EMI",
      "logo_url": "https://cdn.razorpay.com/app/sbin.svg",
      "status": "activated",
      "status_reason": null,
      "enabled": true,
      "requirements": [],
      "updated_at": 1796116800
    }
  },
  "created_at": 1796116801
}
```

> [!NOTE]
>
> **Handy Tips**
>
> * Switching an activated instrument on or off changes only `enabled`, not its status, so no event fires.
> * A group such as `debit_card` has no event of its own. Its status is derived from its members, and the event is sent for the instrument whose status changed.
> * A requirement that several instruments list produces one event per instrument, each with that instrument's requirements.

## 4.4 Handle the Webhook

1. **Verify the signature.** `X-Razorpay-Signature` is the HMAC-SHA256 of the raw body, keyed with your webhook secret, as hex. Read the secret from your environment or secrets manager. Reject an event that does not match.
2. **Acknowledge fast.** Answer with any `2xx` within 5 seconds, then do the work. Razorpay retries anything else with exponential backoff for up to 24 hours. After that, it does not send the event again, so fetch its payment method to catch up.
3. **Expect repeats and any order.** Process each `X-Razorpay-Event-Id` once, and keep the ids you have seen for at least 24 hours. Order events about one instrument by `created_at`, and ignore one older than the last you applied for that instrument. Fetch its payment method when in doubt.

## 4.5 Clarifications in Events

When an instrument moves to `needs_clarification`, the event carries the flagged points in the instrument's `requirements`: the reviewer's or the bank's comment in `reason`, what to send in `description` and `value_type`, and the accepted files or limits in `metadata.constraints`. Show them to the merchant straight from the event. Fetch only to catch up on a missed event. Events never carry an answer or a file.

You cannot answer by webhook. The reply to an event is only its `2xx` acknowledgement, within 5 seconds. The merchant answers with [Upload a document and Answer requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/supply-requirements.md), and an event is sent again when the instrument moves on.

| The event shows | It means | What your platform does |
| - | - | - |
| `status` `needs_clarification`, a requirement with `value_type` `document` | Send a file | Upload it with `POST …/documents`, then answer with its id using `POST …/requirements`. |
| `status` `needs_clarification`, a requirement with `value_type` `text` | Send a value or a reply | Answer with `text` using `POST …/requirements`. |
| A composite with `fulfillment_criteria: one_of` | The merchant chooses one way | Answer one of its `sub_requirements` using `POST …/requirements`. |
| Several requirements | Several points | Answer them all in one call. The status moves on when the last is answered. |
| `status` `under_review` after `needs_clarification` | All points are answered | Nothing. Wait for the next event. |
| `account.payment_methods.requirements.updated` with a requirement back in the list | An answer failed a check | Answer that requirement again using `POST …/requirements`. |

### One Document to Send

HDFC Bank asks again for a clear photo of the shop. The merchant uploads a photo and answers with its id.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Pk3Wn7Hd1Qs9Lc",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "emi/debit_card/banks/hdfc",
      "name": "HDFC Bank debit-card EMI",
      "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
      "status": "needs_clarification",
      "status_reason": null,
      "enabled": false,
      "requirements": [
        {
          "id": "req_Bx4Np7Kt2Hs9Dm",
          "code": "shop_photo",
          "description": "A clear photo of the shop, with the name board visible.",
          "reason": "HDFC Bank: the shop photo shared earlier is blurred.",
          "level": "mandatory",
          "field_path": "business_profile.documents.shop_photo",
          "value_type": "document",
          "metadata": {
            "constraints": {
              "accept": [
                "image/jpeg",
                "image/png"
              ],
              "max_size_mb": 20
            }
          }
        }
      ],
      "updated_at": 1794814200
    }
  },
  "created_at": 1794814201
}
```

### One Value to Correct

HDFC Bank finds that the PAN does not match the GST certificate. The merchant sends the right PAN in text.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Pq8Mz4Tn6Hc2Va",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "emi/debit_card/banks/hdfc",
      "name": "HDFC Bank debit-card EMI",
      "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
      "status": "needs_clarification",
      "status_reason": null,
      "enabled": false,
      "requirements": [
        {
          "id": "req_Pn5Cx2Lw8Rk1Dv",
          "code": "business_pan",
          "description": "The PAN of the business, as printed on the PAN card.",
          "reason": "HDFC Bank: the PAN does not match the name on the GST certificate.",
          "level": "mandatory",
          "field_path": "business_profile.identity_numbers.business_pan",
          "value_type": "text",
          "metadata": {
            "constraints": {
              "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$"
            }
          }
        }
      ],
      "updated_at": 1794814500
    }
  },
  "created_at": 1794814501
}
```

### A Choice

HDFC Bank needs a refund policy page. This is a `one_of` composite: the merchant either shares a website that has the page or replies, and answers only the one chosen.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Pw1Ks7Gb3Nx9Rd",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "emi/debit_card/banks/hdfc",
      "name": "HDFC Bank debit-card EMI",
      "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
      "status": "needs_clarification",
      "status_reason": null,
      "enabled": false,
      "requirements": [
        {
          "id": "req_Tm5Jc8Nq2Lr7Xa",
          "code": "website",
          "description": "Add the page, share a website that has it, or reply with how customers ask for a refund.",
          "reason": "HDFC Bank needs a refund and cancellation policy page on the website.",
          "level": "mandatory",
          "fulfillment_criteria": "one_of",
          "sub_requirements": [
            {
              "id": "req_Vp9Ge4Kd6Ms1Bh",
              "code": "website_url",
              "description": "Your website's address.",
              "reason": null,
              "level": "conditional",
              "field_path": "products.payment_gateway.payment_channels.website.primary",
              "value_type": "text"
            },
            {
              "id": "req_Wn2Lf7Qj5Tz8Cy",
              "code": "clarify_website",
              "description": "Or reply with a comment about your website.",
              "reason": null,
              "level": "conditional",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "text",
              "metadata": {
                "constraints": {
                  "minLength": 50,
                  "maxLength": 300
                }
              }
            }
          ]
        }
      ],
      "updated_at": 1794391617
    }
  },
  "created_at": 1794391618
}
```

### A Document and a Reply at Once

ICICI Bank flags two points in one event: a clear cheque and contact details. The requirements answered earlier are no longer listed. Answer both new points together in one call.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Nc3Lr6Fy9Bd2Wh",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "netbanking/banks/icic",
      "name": "ICICI Bank",
      "logo_url": "https://cdn.razorpay.com/app/icic.svg",
      "status": "needs_clarification",
      "status_reason": null,
      "enabled": false,
      "requirements": [
        {
          "id": "req_Rc7Ch8Qx9Lb0Mn",
          "code": "cancelled_cheque",
          "description": "A clear photo or scan of a cancelled cheque of the settlement bank account.",
          "reason": "ICICI Bank: the account number on the cheque can't be read.",
          "level": "mandatory",
          "field_path": "business_profile.documents.cancelled_cheque",
          "value_type": "document",
          "metadata": {
            "constraints": {
              "accept": [
                "application/pdf",
                "image/jpeg",
                "image/png"
              ],
              "max_size_mb": 20
            }
          }
        },
        {
          "id": "req_Cw1Ct2Rp3Ly4Qs",
          "code": "clarify_website",
          "description": "Reply with how customers can contact the business.",
          "reason": "ICICI Bank: the website has no contact details.",
          "level": "mandatory",
          "field_path": "products.payment_gateway.requirements.requirement_response",
          "value_type": "text",
          "metadata": {
            "constraints": {
              "minLength": 50,
              "maxLength": 300
            }
          }
        }
      ],
      "updated_at": 1795259200
    }
  },
  "created_at": 1795259201
}
```

### Clarification Answered

After the only flagged point is answered, HDFC debit-card EMI is back to `under_review` and its `requirements` list is empty.

```json account.payment_methods.updated theme={null}
{
  "id": "evt_Pz6Hy1Wc4Lm8Qt",
  "entity": "event",
  "event": "account.payment_methods.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "emi/debit_card/banks/hdfc",
      "name": "HDFC Bank debit-card EMI",
      "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
      "status": "under_review",
      "status_reason": null,
      "enabled": false,
      "requirements": [],
      "updated_at": 1794901262
    }
  },
  "created_at": 1794901263
}
```

### An Answer Failed a Later Check

The GSTIN sent earlier fails the check against the GST portal. The instrument's status does not change, so this is the requirements event. The requirement is back in the list, and `reason` says why. Answer it again with `POST …/requirements`.

```json account.payment_methods.requirements.updated theme={null}
{
  "id": "evt_Rq2Fd5Gx8Kt1Mb",
  "entity": "event",
  "event": "account.payment_methods.requirements.updated",
  "mode": "live",
  "account_id": "acc_HQVlm3bnPmccC0",
  "product": "payment_gateway",
  "payload": {
    "instrument": {
      "instrument": "netbanking/banks/icic",
      "name": "ICICI Bank",
      "logo_url": "https://cdn.razorpay.com/app/icic.svg",
      "status": "under_review",
      "status_reason": null,
      "enabled": false,
      "requirements": [
        {
          "id": "req_Ga1Ts2Nb3Hk4Lp",
          "code": "gstin",
          "description": "The GSTIN of the business.",
          "reason": "The GSTIN is not active on the GST portal. Send an active GSTIN.",
          "level": "mandatory",
          "field_path": "business_profile.identity_numbers.gstin",
          "value_type": "text",
          "metadata": {
            "constraints": {
              "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$"
            }
          }
        }
      ],
      "updated_at": 1795000421
    }
  },
  "created_at": 1795003601
}
```

## Next Step

[Cash on Delivery](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/cash-on-delivery.md)
