- Log in to the Merchant Dashboard.
- Go to Payouts Dashboard > Developers > click Webhook in the Payouts section.
- In the Developers - Payouts screen, click Add Webhook URL.
- Enter the URL where you want to receive the updates about the payout events.
- Click Test & Add Webhook.
When you click Test & Add Webhook, Cashfree Payments sends a
LOW_BALANCE_ALERT event to the configured webhook URL to verify the webhook endpoint. The test event confirms that the endpoint is reachable, can process webhook requests successfully, and returns an HTTP 200 OK response. After the endpoint is validated, Cashfree delivers all subsequent webhook events to the configured URL.For the LOW_BALANCE_ALERT test event, the signature and timestamp are included in the webhook payload. For all other V2 webhook events, the signature and timestamp are sent in the request headers.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:TRANSFER_SUCCESS
Sent when a transfer is attempted successfully.What does the response parameter ‘acknowledged’ mean
The acknowledged parameter value conveys if the beneficiary received the funds by checking its value. Ack = 1 or 0. 1 denotes the beneficiary received funds, and 0 denotes the beneficiary had not received funds. The cash flow happens as explained below:- Debit: The debit of the transfers happens on the remitter account. After a successful debit, the beneficiary bank does further processing. When only the debit is successful, Ack = 0.
- Credit: The beneficiary bank credits the fund to the account. The transfer is sent from the remitter bank to the beneficiary bank after a successful debit. When the credit to the end beneficiary is successful, Ack = 1.
TRANSFER_APPROVED
The webhook is sent when Approver approves the transfer through the dashboard or via API.TRANSFER_FAILED
Sent when a transfer attempt fails.TRANSFER_REVERSED
Sent when the beneficiary bank reverses a transfer.CREDIT_CONFIRMATION
Sent when the balance credit is confirmed.TRANSFER_ACKNOWLEDGED
Sent when the bank acknowledges a transfer.TRANSFER_REJECTED
Sent when a transfer is rejected.BENEFICIARY_INCIDENT
Sent when a beneficiary incident is created or resolved.LOW_BALANCE_ALERT
Sent when the payout balance is low.
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. If we do not receive the status after 72 hours, you must manually reconcile the transaction.
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:- Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair.
- Sort the array based on keys.
- Concatenate all the values in this array and the resultant is the post data (say, postData).
- Encrypt postData using SHA-256, then base64-encode it.
- Now verify if both the signature calculated and the signature received a match.
- Proceed further if it matches, else discard the request.
To verify the signature, use the active API key that was generated first (old API key) and not the latest API keys. Do not go live without verifying the signature.
Node
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 communication at regular intervals. If we do not receive the response after a 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 you do not receive notifications from Cashfree Payments as expected, contact our support team by filling out the Support Form.Development and testing webhooks
When you decide to use webhooks, first, you need to have a URL to receive notifications. This URL should be an HTTPS endpoint and accept JSON payload with thePOST method. The easiest way to test out webhooks is with tools like Ngrok, Webhook.site, Beeceptor etc.
Simply use these services to create a new endpoint and put it in Cashfree. When a webhook has been sent through, you should see it on these tools. You can inspect the entire payload and share it with colleagues for further development and testing.
IPs to whitelist
When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree: UAT:52.66.25.127
15.206.45.168 Prod:
52.66.101.190
3.109.102.144 Port: 443 (Secured)