Webhooks

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction or instrument happen. Webhooks help you receive automatic updates and are significant for completing the integration with Cashfree.

Cashfree Payments sends the following webhooks:

1. Instrument
2. Transfer

To configure webhooks,

1. Go to the Merchant dashboard > Accounts Dashboard > Developers > click Webhook in the API Banking section.
2. In the Developers - Banking screen, click Add Webhooks.
3. Choose the Webhook Type and then Webhook Sub Type based on your requirement.
4. Enter the URL where you want to receive the updates about the BaaS events.

5. Click Test & Add Webhook.

{
  "data": {
    "transfer": {
      "customer_id": "cust_123",
      "transfer_id": "transfer_123",
      "instrument_id": "inst_123",
      "bank_reference_number": "1639124531203578"
    }
  },
  "type": "TRANSFER_SUCCESS",
  "version": 1,
  "event_time": "2022-02-06T05:33:55Z"
}

Signature Verification

Cashfree Payments sends a signature and timestamp alongside every webhook in headers named: X-Cashfree-Signature and X-Cashfree-Timestamp. Verifying this signature (passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree BaaS Product and verify if the request has not been tampered with.

Following are the steps to verify Cashfree BaaS events signature:

To verify the signature at your end, you will need your oldest Cashfree ACTIVE BaaS Account secret key.

timestamp := 1617695238078; 
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));

Webhook Retries

Cashfree 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 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 acknowledgment due to any reason, we retry to establish the communication at regular intervals. If we do not receive a 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 at [email protected].