> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Transfer Webhook Events
> Configure Transfer webhooks to receive event-based notifications whenever a wallet transfer changes status in your PPI integration.
Webhooks are event-based notifications that you receive when a specific event related to a wallet transfer occurs.
In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, Cashfree may send the same webhook more than once for the same event. To prevent unintended side effects, implement idempotency (ensuring a duplicate webhook produces the same result as processing it once) in your webhook handler to handle duplicate deliveries.
## Webhook signature
Cashfree includes the webhook signature in the request header. The following is a sample header from a webhook request.
| Header name | Header value |
| ------------------- | :------------------------------------------: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |
| x-webhook-version | 2025-01-01 |
Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.
Verifying the signature is mandatory before processing any webhook. Refer to [Signature Verification](/api-reference/prepaid-payment-instruments/webhook-signature-verification#webhook-signature-verification) for more details.
## Transfer webhook events
Cashfree triggers the following events at different stages of a wallet transfer:
| Event | Description |
| :---------------------- | :------------------------------------------------------------------------------------ |
| PPI\_TRANSFER\_SUCCESS | The transfer is successfully credited to the beneficiary's account. |
| PPI\_TRANSFER\_FAILED | The transfer cannot be processed due to an error or rejection by the bank. |
| PPI\_TRANSFER\_REVERSED | The beneficiary bank returns the transfer after initial processing. |
| PPI\_TRANSFER\_REJECTED | Cashfree rejects the transfer before it reaches the bank due to a validation failure. |
The following examples show the webhook payload for each event type.
```json theme={"dark"}
{
"event_type": "PPI_TRANSFER_SUCCESS",
"event_time": "2026-05-18T10:00:45Z",
"data": {
"user_id": "usr_001",
"wallet_id": "wlt_001",
"cf_transfer_id": "1003",
"transfer_id": "txn_ext_003",
"amount": 500.00,
"transfer_mode": "IMPS",
"actual_mode": "IMPS",
"sub_wallet": {
"cf_sub_wallet_id": "swlt_001",
"name": "Primary Wallet",
"type": "PRIMARY",
"status": "ACTIVE",
"balance": 4500.00,
"available_balance": 4500.00,
"funds_on_hold": 0.00
},
"status": "SUCCESS",
"status_code": "ACKNOWLEDGED_VIA_BENE_BANK",
"bank_reference_number": "BNKREF789012",
"bene_details": {
"bene_id": "bene_001",
"bene_instrument_id": "instr_001"
},
"purpose": "salary",
"remarks": "Monthly salary",
"initiated_at": "2026-05-18T10:00:00Z",
"processed_at": "2026-05-18T10:00:45Z",
"notes": null
}
}
```
```json theme={"dark"}
{
"event_type": "PPI_TRANSFER_FAILED",
"event_time": "2026-05-18T10:00:01Z",
"data": {
"user_id": "usr_001",
"wallet_id": "wlt_001",
"cf_transfer_id": "1004",
"transfer_id": "txn_ext_004",
"amount": 500.00,
"transfer_mode": "IMPS",
"actual_mode": null,
"sub_wallet": {
"cf_sub_wallet_id": "swlt_001",
"name": "Primary Wallet",
"type": "PRIMARY",
"status": "ACTIVE",
"balance": 5000.00,
"available_balance": 5000.00,
"funds_on_hold": 0.00
},
"status": "FAILED",
"status_code": "INSUFFICIENT_BALANCE",
"bank_reference_number": null,
"bene_details": {
"bene_id": "bene_001",
"bene_instrument_id": "instr_001"
},
"purpose": "salary",
"remarks": "Monthly salary",
"initiated_at": "2026-05-18T10:00:00Z",
"processed_at": "2026-05-18T10:00:01Z",
"notes": null
}
}
```
```json theme={"dark"}
{
"event_type": "PPI_TRANSFER_REVERSED",
"event_time": "2026-05-18T10:05:00Z",
"data": {
"user_id": "usr_001",
"wallet_id": "wlt_001",
"cf_transfer_id": "1005",
"transfer_id": "txn_ext_005",
"amount": 500.00,
"transfer_mode": "IMPS",
"actual_mode": "IMPS",
"sub_wallet": {
"cf_sub_wallet_id": "swlt_001",
"name": "Primary Wallet",
"type": "PRIMARY",
"status": "ACTIVE",
"balance": 5000.00,
"available_balance": 5000.00,
"funds_on_hold": 0.00
},
"status": "REVERSED",
"status_code": "RETURNED_FROM_BENE",
"bank_reference_number": "BNKREF_REV001",
"bene_details": {
"bene_id": "bene_001",
"bene_instrument_id": "instr_001"
},
"purpose": "salary",
"remarks": "Monthly salary",
"initiated_at": "2026-05-18T10:00:00Z",
"processed_at": "2026-05-18T10:05:00Z",
"notes": null
}
}
```
```json theme={"dark"}
{
"event_type": "PPI_TRANSFER_REJECTED",
"event_time": "2026-05-18T10:00:01Z",
"data": {
"user_id": "usr_001",
"wallet_id": "wlt_001",
"cf_transfer_id": "1006",
"transfer_id": "txn_ext_006",
"amount": 500.00,
"transfer_mode": "IMPS",
"actual_mode": null,
"sub_wallet": {
"cf_sub_wallet_id": "swlt_001",
"name": "Primary Wallet",
"type": "PRIMARY",
"status": "ACTIVE",
"balance": 5000.00,
"available_balance": 5000.00,
"funds_on_hold": 0.00
},
"status": "REJECTED",
"status_code": "BENE_BLACKLISTED",
"bank_reference_number": null,
"bene_details": {
"bene_id": "bene_001",
"bene_instrument_id": "instr_001"
},
"purpose": "salary",
"remarks": "Monthly salary",
"initiated_at": "2026-05-18T10:00:00Z",
"processed_at": "2026-05-18T10:00:01Z",
"notes": null
}
}
```
## Transfer webhook payload fields
The webhook payload contains important metadata in its top-level fields.
| Field | Type | Description |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `event_type` | `string` | Type of transfer event: `PPI_TRANSFER_SUCCESS`, `PPI_TRANSFER_FAILED`, `PPI_TRANSFER_REVERSED`, or `PPI_TRANSFER_REJECTED` |
| `event_time` | `string` | The UTC timestamp when the event occurred, in ISO 8601 format |
| `data` | `object` | Transfer-specific event details |
## Transfer data fields
Transfer webhook events contain the following fields inside `data`:
| Field | Type | Description |
| --------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id` | `string` | Identifier of the user who initiated the transfer |
| `wallet_id` | `string` | Identifier of the wallet from which the transfer was made |
| `transfer_id` | `string` | Your unique identifier for the transfer transaction |
| `cf_transfer_id` | `string` | Cashfree's unique identifier for the transfer transaction |
| `amount` | `number` | Transfer amount in INR |
| `transfer_mode` | `string` | Transfer mode requested: `RTGS`, `NEFT`, `IMPS`, or `UPI` |
| `actual_mode` | `string` | Transfer mode actually used to process the transaction. Set only when the transfer reaches the bank (`SUCCESS` or `REVERSED`); `null` otherwise |
| `sub_wallet` | `object` | Details of the sub-wallet from which funds were transferred |
| `sub_wallet.cf_sub_wallet_id` | `string` | Cashfree's unique identifier for the sub-wallet |
| `sub_wallet.name` | `string` | Name of the sub-wallet |
| `sub_wallet.type` | `string` | Type of the sub-wallet (for example, `PRIMARY`, `FULL_KYC_PPI`, `GIFT_PPI`) |
| `sub_wallet.status` | `string` | Current status of the sub-wallet (for example, `ACTIVE`, `SUSPENDED`) |
| `sub_wallet.balance` | `number` | Total balance in the sub-wallet in INR |
| `sub_wallet.available_balance` | `number` | Balance available for new transfers after accounting for funds on hold, in INR |
| `sub_wallet.funds_on_hold` | `number` | Amount reserved for in-flight transfers not yet settled, in INR |
| `status` | `string` | Current status of the transfer: `SUCCESS`, `FAILED`, `REVERSED`, or `REJECTED` |
| `status_code` | `string` | Granular status code for the transfer (for example, `ACKNOWLEDGED_VIA_BENE_BANK`, `INSUFFICIENT_BALANCE`, `RETURNED_FROM_BENE`, `BENE_BLACKLISTED`) |
| `bank_reference_number` | `string` | Bank reference number for the transaction. Set only when the transfer reaches the bank (`SUCCESS` or `REVERSED`); `null` otherwise |
| `bene_details` | `object` | Beneficiary details for the transfer |
| `bene_details.bene_id` | `string` | Your unique identifier for the beneficiary |
| `bene_details.bene_instrument_id` | `string` | Your unique identifier for the beneficiary instrument |
| `purpose` | `string` | Purpose of the transfer |
| `remarks` | `string` | Additional remarks for the transfer |
| `notes` | `object \| null` | Custom key-value pairs provided during transfer creation. Returns `null` if no notes were set. |
| `initiated_at` | `string` | Timestamp when the transfer was initiated |
| `processed_at` | `string` | Timestamp when the transfer reached a terminal state |