Webhooks

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

Cashfree sends the following webhooks for Payment Gateway:

Incident Service

Cashfree will notify you whenever we create an incident at our end. An incident implies that the issuing bank is facing high failure rates or has scheduled a maintenance activity during that time. The former could be due to many reasons and until the failure rates go down, we would recommend customers to use alternative payment instruments.

There are two channels through which we notify. You can subscribe to either of the channels by adding your email address and webhook endpoint in the merchant dashboard.

  1. Email - Cashfree sends an email alert when an issuer is facing downtime or a scheduled incident.

  2. Webhooks - Cashfree will invoke a server to server call whenever an incident is created. You can use this webhook and update your payment page accordingly.

Webhook Schema

Sample Payload for Creation of Incident

{
"data": {
"incident": {
"end_time": null,
"id": "INCIDENT_MEDIUM_KarurVysyaBank_a7259c79-25a8-4b86-bcab-71562a85c386",
"impact": "MEDIUM",
"message": "We are facing issues with KVB bank UPI payments. ",
"start_time": "2021-04-16T14:00:00+05:30",
"status": "OPEN",
"type": "UNSCHEDULED"
},
"instruments": {
"upi": {
"issuers": [
"Karur Vysya Bank"
]
}
}
},
"event_time": "2021-04-16T14:10:36+05:30",
"type": "HEALTH_ALERT",
"version": 1
}

Sample Payload When Incident is Resolved

{
"data": {
"incident": {
"end_time": "2021-04-16T18:20:24+05:30",
"id": "INCIDENT_MEDIUM_KarurVysyaBank_a7259c79-25a8-4b86-bcab-71562a85c386",
"impact": "MEDIUM",
"message": "Payment mode up",
"start_time": "2021-04-16T14:00:00+05:30",
"status": "RESOLVED",
"type": "UNSCHEDULED"
},
"instruments": {
"upi": {
"issuers": [
"Karur Vysya Bank"
]
}
}
},
"event_time": "2021-04-16T18:20:24+05:30",
"type": "HEALTH_ALERT",
"version": 1
}

Payload

Field

Description

Example

Mandatory

end_time

Null when an incident is created. Or end time when incident is resolved

2021-04-16T15:10:36+05:30

N

start_time

Time since we have seen this incident

2021-04-16T14:10:36+05:30

Y

id

Incident id

Alphanumeric with special characters - _,-,

Y

impact

Impact of the downtime

HIGH, MEDIUM, LOW

Y

message

Human readable message

N

status

Status of the incident. OPEN when the incident is created. RESOLVED once the incident is resolved. UPDATE once we update the incident with any more details.

OPEN, UPDATE, RESOLVED

Y

type

Is this a scheduled or an unscheduled downtime?

SCHEDULED, UNSCHEDULED

Y

instruments

Refers to the payment mode. This will contain a nested object. One of the following - upi, net_banking, card, wallet

Y

upi.issuers

Issuers which are impacted

Array

N

net_banking.issuers

Net banking banks which are impacted

Array

N

wallet.issuers

Wallets which are impacted

Array

N

card.type

Card types which are impacted

CREDIT_CARD, DEBIT_CARD, ALL

N

card.scheme

Card schemes which are impacted

MASTER, VISA, RUPAY, MAESTRO, AMEX, ALL

N

card.issuers

Banks which are impacted

Array

N

event_time

Time when this webhook was created

Y

type

Type of webhook

HEALTH_ALERT

Y

version

Version of webhook

You should build your parsing logic wrt to this version.

Y

Children

Optional

Type

Possible values

wallet

Y*

Child attributes

Available below

net_banking

Y*

Child attributes

Available below

upi

Y*

Child attributes

Available below

card

Y*

Child attributes

Available below

* At least one of the children needs to be present

Wallet

Children

Optional

Type

Possible values

issuers

N

Text

See list of wallet issuers here

Net Banking

Children

Optional

Type

Possible values

issuers

N

Array

See list of issuers here

UPI

Children

Optional

Type

Possible values

issuers

N

Array

See list of issuers here

Card

Children

Optional

Type

Possible values

type

N

Text

CREDIT_CARD, DEBIT_CARD, ALL

scheme

N

Text

MASTER, VISA, RUPAY, MAESTRO, AMEX, ALL

issuers

N

Array

See list of issuers here

Payload Headers

Cashfree will send two custom headers for every webhook being invoked by our system.

Name

Desc

Example

x-cashfree-timestamp

Timestamp for this event. Used to generate signature

1618562436364

x-cashfree-signature

Cashfree signature for this webhook

ke+K3gR8GssH9AMfJm+0+8jGIL1Mq7hOheP9w36/hL0=

Signature Generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

//The payload here refers to the raw request sent by
Cashfree to your endpoint. No modifications need to be
done to this payload.
payload := {"data":{"bank_name":"Test Bank",
"card_type":"Visa","health":"DEGRADED",
"incident_end_time":"2021-04-07T00:20:30",
"incident_id":"INCIDENT_HIGH_Test Bank_954b95zz-f11a-test-abcd-0eb0e8608847",
"incident_impact":"High",
"incident_start_time":"2021-04-06T00:20",
"incident_type":"Scheduled",
"is_resolved":false,
"issuers":[],
"message":"We are facing high failure issues in Payment gateway at the moment and will keep you updated about the issue.",
"payment_gateway":null,"payment_mode":"DEBIT_CARD",
"scope":"PaymentMode"},
"type":"HEALTH_ALERT","version":1}
# timestamp is present in the header x-cashfree-timestamp
timestamp := 1617695238078
signedPayload := $timestamp.$payload
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey))

Bank Names

Bank Name

Axis Bank

Bank of Baroda - Retail Banking

Bank of India

Bank of Maharashtra

Canara Bank

Catholic Syrian Bank

Central Bank of India

City Union Bank

Deutsche Bank

DBS Bank Ltd

DCB Bank - Personal

Dhanlakshmi Bank

Federal Bank

HDFC Bank

ICICI Bank

IDBI Bank

IDFC Bank

Indian Bank

Indian Overseas Bank

IndusInd Bank

Jammu and Kashmir Bank

Karnataka Bank Ltd

Karur Vysya Bank

Kotak Mahindra Bank

Laxmi Vilas Bank - Retail Net Banking

Punjab & Sind Bank

Punjab National Bank - Retail Net Banking

RBL Bank

Saraswat Bank

South Indian Bank

Standard Chartered Bank

State Bank Of India

Tamilnad Mercantile Bank Ltd

UCO Bank

Union Bank of India

Yes Bank Ltd

Bank of Baroda - Corporate

Bank of India - Corporate

DCB Bank - Corporate

Lakshmi Vilas Bank - Corporate

Punjab National Bank - Corporate

State Bank of India - Corporate

Union Bank of India - Corporate

Axis Bank Corporate

Dhanlaxmi Bank Corporate

ICICI Corporate Netbanking

Ratnakar Corporate Banking

Shamrao Vithal Bank Corporate

Equitas Small Finance Bank

Yes Bank Corporate

Bandhan Bank- Corporate banking

Barclays Corporate- Corporate Banking - Corporate

Indian Overseas Bank Corporate

City Union Bank of Corporate

HDFC Corporate

Shivalik Bank

AU Small Finance

Bandhan Bank - Retail Net Banking

Shamrao Vitthal Co-operative Bank

Tamil Nadu State Co-operative Bank

All Banks (Note: This parameter will be sent when all banks are having a downtime)

Wallet Names

Name of the wallet

FreeCharge

MobiKwik

Ola Money

Reliance Jio Money

Airtel Money

Paytm

Amazon Pay

PhonePe