Create Account

Webhooks are events that notify you about the payment status. All Payout integrations should establish a webhook to listen to payout events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events.

Webhooks help you receive automatic updates and are significant for completing the integration with Cashfree Payments. Webhooks are triggered with a request from your side, for example, when a transfer fails or when a daily report is available. Requests get processed both synchronously and asynchronously. In rare scenarios, for some payment methods, the outcome may take a longer duration to confirm. Cashfree Payments notifies you once we get updates from the bank about the payment status.

Do not go live without signature verification if you are using webhooks.

To configure webhooks,

  1. Go to **Payouts Dashboard** > **Developers** > click **Webhook** in the **Payouts** section.

  2. In the **Developers - Payouts** screen, click **Add Webhook URL**.

  3. Enter the URL where you want to receive the updates about the [payout events](🔗).

1428


Add Webhook

  1. Click **Test & Add Webhook**.



# Webhook Events

Payouts webhooks enable you to receive updates about all event-driven activities originating from your account. Below is the list of payouts webhooks:

EventsNotifications
[TRANSFER_SUCCESS​](🔗)Transfer successful at the bank and account debited.
[TRANSFER_FAILED](🔗)Sent whenever a transfer attempt fails.
[TRANSFER_REVERSED](🔗)Transfer reversed by the beneficiary bank.
[CREDIT_CONFIRMATION](🔗)Confirmation of balance credit.
[​TRANSFER_ACKNOWLEDGED​](🔗)After the beneficiary bank has deposited the money it confirms the transfer.
[TRANSFER_REJECTED](🔗)Transfer rejected by Cashfree Payments.
[BENEFICIARY_INCIDENT](🔗)Sent whenever a beneficiary incident is created/resolved.
[LOW_BALANCE_ALERT​](🔗)Payouts recharge account low balance alert.

## TRANSFER_SUCCESS​

Sent when a transfer is attempted successfully at the bank and the beneficiary account is credited.

ParametersDescription
eventIt contains the name of the event which just occurred. Value = TRANSFER_SUCCESS.
transferIdId of the transfer passed by the merchant.
referenceIdId of the transfer generated by Cashfree Payments.
acknowledgedThe flag indicates if the beneficiary bank has acknowledged the transfer.
eventTimeTransfer initiation time.
utrUnique transaction reference number provided by the bank.
signatureA unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments.


## ​TRANSFER_FAILED

Sent when a transfer attempt fails.

ParametersDescription
eventIt contains the name of the event which just occurred. Value = TRANSFER_FAILED.
transferIdId of the transfer passed by the merchant
referenceIdId of the transfer generated by Cashfree Payments.
reasonReason for failure.
signatureA unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments.


## TRANSFER_REVERSED

Sent when the beneficiary bank reverses a transfer.

ParametersDescription
eventIt contains the name of the event which just occurred. Value = TRANSFER_REVERSED.
transferIdId of the transfer passed by the merchant.
referenceIdId of the transfer generated by Cashfree Payments.
eventTimeTime at which the transfer was reversed.
reasonReason for failure.
signatureA unique string which helps distinguish that the request is genuine and initiated by Cashfree Payments.


## CREDIT_CONFIRMATION

Sent when the balance credit is confirmed.

ParametersDescription
eventIt contains the name of the event which just occurred. Value = CREDIT_CONFIRMATION.
ledgerBalanceThe overall balance of ledger.
amountAmount deposited.
utrUnique transaction reference number provided by the bank.
signatureA unique string which helps distinguish that the request is genuine and initiated by Cashfree Payments.


## TRANSFER_ACKNOWLEDGED

Sent when the bank acknowledges a transfer.

ParametersDescription
eventIt contains the name of the event which just occurred. Value = TRANSFER_ACKNOWLEDGED.
transferIdId of the transfer passed by the merchant.
referenceIdId of the transfer generated by Cashfree Payments.
acknowledgedThe flag which illustrates if the beneficiary bank acknowledges the transfer.
signatureA unique string which helps distinguish that the request is genuine and initiated by Cashfree Payments.


## TRANSFER_REJECTED

Sent when a transfer is rejected.

ParameterDescription
eventIt contains the name of the event which just occurred. Value = TRANSFER_REJECTED.
transferIdId of the transfer passed by the merchant.
referenceIdId of the transfer generated by Cashfree Payments.
reasonReason for rejection.
signatureA unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments.


## BENEFICIARY_INCIDENT

Sent when a beneficiary incident is created or resolved.

ParameterDescription
eventIt contains the name of the event which just occurred. Value = BENEFICIARY_INCIDENT.
beneEntityThe entity of the beneficiary (BANK).
idIdentifier of the incident.
modeMode of the incident (IMPS/NEFT)
startedAtStart time of the incident.
statusStatus of the incident (ACTIVE/RESOLVED).
isScheduledScheduled or unscheduled incident (true or false).
severityThe severity of the incident (LOW/HIGH).
entityNameName of the entity on which incident is created (Bank Name).
entityCodeCode of the entity on which incident is created.
resolvedAtResolution time of the incident.


## LOW_BALANCE_ALERT

Sent when the payout balance is low.

ParameterDescription
eventIt contains the name of the event which just occurred. Value = LOW_BALANCE_ALERT
currentBalanceThe current balance of the beneficiary account
alertTimeAlert initiation time.
signatureA unique string which helps distinguish that the request is genuine and initiated by Cashfree Payments.

**Delay in Receiving the Response**

Cashfree Payments receives a response from the bank with the status of the transfer instantly. At times the response may get delayed due to various reasons, and the transaction status will be marked as Pending, till we get a response.

Cashfree Payments polls the transaction status from the bank for the next 72 hours. In case we do not receive the status of a transaction after 72 hours, the transaction needs to be manually reconciled.



## Signature Verification

Cashfree Payments sends a signature alongside every webhook, verifying this signature ( passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree Payments.

We strongly recommend whitelisting Cashfree Payments production IP to help make your communication with us more secure.

Following are the steps to verify Cashfree Payments signature:

  1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair.

  2. Sort the array based on keys.

  3. Concatenate all the values in this array and resultant is the post data (say, postData).

  4. **postData** needs to be encrypted using SHA-256, and then base64 encoded.

  5. Now verify if both the signature calculated and the signature received match.

  6. Proceed further if it matches, else discards the request.

Our libraries also support signature verification. To verify the signature returned by Cashfree Payments call the following methods from the library.

Below are the code snippets that can help you verify the signature:


# Webhook Retries
Cashfree Payments webhooks service does its best to deliver events to your webhook endpoint. It is best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process.
Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body gets ignored. Any response code outside the 200 range, including 3xx codes, indicates that you did not receive the webhook.
When Cashfree Payments does not get the acknowledgement due to any reason, we retry to establish the communication at regular intervals. If we do not receive the response after few attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.
If do not receive notifications from Cashfree Payments as expected, contact our support team at [[email protected]](🔗).