Skip to main content
Webhooks are event-based notifications that are received when a specific event related to the Wallet occurs.
In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.

​
Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.
Header nameHeader value
content-length1099
x-webhook-attempt1
content-typeapplication/json
x-webhook-signature07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI=
x-webhook-timestamp1746427759733
x-webhook-version2025-01-01
Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising 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.

​
Wallet Credit events

The following are examples of webhook events that you may receive. 
{
  "event_type": "PPI_CREDIT_SUCCESS",
  "event_time": "2006-01-02T15:04:05Z",
  "data": {
    "credit_id": "CREDIT126345",
    "cf_credit_id": "8901234567890123456",
    "wallet_id": "WALLET936721",
    "user_id": "USER827364",
    "amount": 100.5,
    "sub_wallet": {
      "cf_sub_wallet_id": "35246543210987654321",
      "name": "Gift Wallet",
      "type": "GIFT_PPI",
      "status": "ACTIVE",
      "balance": 1500.75
    },
    "issued_gift_code": {
      "code": "GIFT-2025-XYZ123",
      "value": 100.5,
      "expiry": "2025-12-31T23:59:59Z"
    },
    "status": "SUCCESS",
    "remarks": "Refund for order 123",
    "initiated_at": "2025-09-02T10:15:30Z",
    "processed_at": "2025-09-02T10:20:45Z"
  }
}

​
Wallet Transfer events

The following are examples of transfer webhook events that you may receive for different transfer statuses. 
{
  "event_type": "PPI_TRANSFER_SUCCESS",
  "event_time": "2006-01-02T15:04:05Z",
  "data": {
    "user_id": "USER827364",
    "wallet_id": "WALLET936721",
    "cf_transfer_id": "8901234567890123456",
    "transfer_id": "TRANSFER123456",
    "amount": 500.75,
    "transfer_mode": "NEFT",
    "sub_wallet": {
      "cf_sub_wallet_id": "35246543210987654321",
      "name": "Cashfree payout Wallet",
      "type": "FULL_KYC_PPI",
      "status": "ACTIVE",
      "balance": 8749.55
    },
    "status": "SUCCESS",
    "status_code": "COMPLETED",
    "bank_ref_no": "BNK202502101530001",
    "bene_details": {
      "bene_id": "BENE123",
      "cf_bene_instrument_id": "35246543210987654323",
      "instrument_details": {
        "bank_account_number": "1234567890",
        "ifsc": "HDFC0000123"
      }
    },
    "purpose": "BUSINESS",
    "remarks": "Vendor payment",
    "notes": {
      "example_key": "example_value",
      "example_key2": "example_value2"
    },
    "initiated_at": "2025-09-02T10:15:30Z",
    "processed_at": "2025-09-02T10:17:45Z"
  }
}

​
Wallet Credit webhook payload fields

The webhook payload contains important metadata in its top-level fields.
FieldTypeDescription
event_typestringIndicates the type of event that triggered the webhook.
event_timestringThe UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
dataobjectContains event-specific details related to this feature.

​
Wallet Transfer webhook payload fields

Transfer webhook events contain additional fields specific to transfer operations:
FieldTypeDescription
event_typestringType of transfer event: PPI_TRANSFER_SUCCESS, PPI_TRANSFER_FAILED, PPI_TRANSFER_REVERSED, or PPI_TRANSFER_REJECTED
event_timestringThe UTC timestamp when the event occurred, in ISO 8601 format
dataobjectTransfer-specific event details
data.user_idstringIdentifier of the user who initiated the transfer
data.wallet_idstringIdentifier of the wallet from which the transfer was made
data.transfer_idstringYour unique identifier for the transfer transaction
data.cf_transfer_idstringCashfree’s unique identifier for the transfer transaction
data.amountnumberTransfer amount
data.transfer_modestringTransfer mode used: RTGS, NEFT, IMPS, or UPI
data.sub_walletobjectDetails of the sub-wallet from which funds were transferred
data.statusstringFinal status of the transfer: SUCCESS, FAILED, REVERSED, or REJECTED
data.status_codestringStatus code for detailed tracking: COMPLETED, INVALID_ACCOUNT_FAIL, REVERSED, or REJECTED
data.bank_ref_nostringBank reference number for the transaction (null if transfer failed before processing)
data.bene_detailsobjectBeneficiary details including instrument information
data.purposestringPurpose of the transfer
data.remarksstringAdditional remarks for the transfer
data.notesobjectCustom key-value pairs provided during transfer creation
data.initiated_atstringTimestamp when the transfer was initiated
data.processed_atstringTimestamp when the transfer was completed/failed
Verifying the signature is mandatory before processing any response. Refer to Signature Verification for more details.