Payment Webhook Setup | Cashfree Payments

When building Cashfree integrations, you might want your applications to receive events as they occur in your Cashfree account so that your back-end systems can execute actions accordingly. To enable real-time event notifications, register your webhook endpoints with Cashfree (Developers > Webhooks). These endpoints will receive HTTP POST requests containing JSON payloads whenever specific events happen in your Cashfree account. This allows your application to react promptly to changes such as successful payments, failed transactions, or new chargebacks.

Payment Webhooks

Refund Webhooks

Settlement Webhooks

Token Vault Webhooks

Subscription Webhooks

Payment Forms Webhooks

Verify webhooks

It is essential to verify webhooks to prevent manipulation of the webhook payload through man-in-the-middle (MITM) attacks. Use webhook signatures to authenticate Cashfree Payments webhooks, and proceed with further actions only after successful verification. For comprehensive security measures including IP whitelisting and SSL configuration, refer to the Webhook Security Checklist.

Cashfree generates the webhook signature based on the raw payload, not the parsed payload. You can refer to how the popular JavaScript framework NestJS provides a hook for accessing the raw body.

Test webhooks

Test your webhooks in the sandbox environment before going live to check payloads and integration. Configuring your webhooks, from the dashboard, in the test environment and events triggered in test transactions will send webhooks to the configured endpoint.

You can create endpoint URLs and test webhooks using tools like webhook.site or create a tunnel to your localhost using tools like ngrok.

Retry webhooks policy

You can also customise and define a retry policy for all webhooks that do not get delivered with a 200 response. Log in to the Merchant Dashboard and go to Payment Gateway > Developers > Webhooks. We will trigger webhooks to your URLs according to the defined retry policy for each endpoint till the time we get a 200 response. To configure the retry policy: You will see two types of URL listed -

NOTIFY_URL - This is the default configuration added to your account and configurations here cannot be edited or deleted. This configuration will be applicable to only the URLs sent in the notify_url param of Create Order API within the order_meta object
Your custom configured URLs: You can click Edit and follow the steps on the screen to define a custom retry policy. A default policy is applied to all URLs.

Resend webhooks

This feature is only available for payment webhooks

There are various reasons because of which you might need to resend a webhook response again to your endpoint. Common reasons include service level downtime, failure to register webhook payload etc. With Cashfree, you can resend the webhooks that have been previously triggered. Simply log on to your dashboard and follow the steps below:

Go to Webhooks under Developer section and go to ‘Logs’
On the top right, click the Batch Resend button

You will see three options here:
1. Text - simple enter transaction IDs (comma separated) in the text box and click ‘Resend’. Transaction IDs are the same as Entity IDs listed on the logs dashboard
2. File - upload the file in the required format (downloadable from the dashboard) with required Transaction IDs and click ‘Resend’
3. Time Duration - select the time period (max. allowed duration is 24 hours) and click ‘Resend’

Webhook signature verification

Cashfree generates the webhook signature based on the raw payload, not the parsed payload. You can refer to how the popular JavaScript framework NestJS provides a hook for accessing the raw body.

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

The timestamp is present in the header x-webhook-timestamp.
The actual signature is present in the header x-webhook-signature.

signature-verification

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

SDK verification (built-in approach)

var express = require('express')
import { Cashfree } from "cashfree-pg"; 
var app = express()

Cashfree.XClientId = "<x-client-id>";
Cashfree.XClientSecret = "<x-client-secret>";
Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

app.post('/webhook', function (req, res) {
try {
Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
} catch (err) {
console.log(err.message)
}
})

import (
  cashfree "github.com/cashfree/cashfree-pg/v4"
)

// Route
e.POST("/webhook", _this.Webhook)

// Controller
func (_this *WebhookRoute) Webhook(c echo.Context) error {
  	clientId := "<x-client-id>"
		clientSecret := "<x-client-secret>"
		cashfree.XClientId = &clientId
		cashfree.XClientSecret = &clientSecret
		cashfree.XEnvironment = cashfree.SANDBOX

    signature := c.Request().Header.Get("x-webhook-signature")
    timestamp := c.Request().Header.Get("x-webhook-timestamp")

    body, _ := ioutil.ReadAll(c.Request().Body)
    rawBody := string(body)
    webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
    if err != nil {
		fmt.Println(err.Error())
	} else {
		fmt.Println(webhookEvent.Object)
	}
}

<?php

$inputJSON = file_get_contents('php://input');

$expectedSig = getallheaders()['x-webhook-signature'];
$ts = getallheaders()['x-webhook-timestamp'];

if(!isset($expectedSig) || !isset($ts)){
    echo "Bad Request";
    die();
}

\Cashfree\Cashfree::$XClientId = "<x-client-id>";
\Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
$cashfree = new \Cashfree\Cashfree();

try {
 $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
} catch(Exception $e) {
  // Error if signature verification fails
}
?>

from cashfree_pg.api_client import Cashfree

@app.route('/webhook', methods = ['POST'])
def disp():
		# Get the raw body from the request
    raw_body = request.data

    # Decode the raw body bytes into a string
    decoded_body = raw_body.decode('utf-8')

    #verify_signature
    timestamp = request.headers['x-webhook-timestamp']
    signature = request.headers['x-webhook-signature']

		cashfree = Cashfree()
		cashfree.XClientId = "<app_id>"
		cashfree.XClientSecret = "<secret_key>"
		try:
			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
		except:
			# If Signature mis-match

import com.cashfree.*;

@PostMapping("/my-endpoint")
public String handlePost(HttpServletRequest request) throws IOException {
    Cashfree.XClientId = "<x-client-id>";
		Cashfree.XClientSecret = "<x-client-secret>";
		Cashfree.XEnvironment = Cashfree.SANDBOX;

  	StringBuilder stringBuilder = new StringBuilder();
    BufferedReader bufferedReader = null;

    try {
      bufferedReader = request.getReader();
      String line;
      while ((line = bufferedReader.readLine()) != null) {
              stringBuilder.append(line).append('\n');
      }


      String rawBody = stringBuilder.toString();
      String signature = request.getHeader("x-webhook-signature");
      String timestamp = request.getHeader("x-webhook-timestamp");

      Cashfree cashfree = new Cashfree();
      PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

    } catch (Exception e) {
            // Error if verification fails
    } finally {
         if (bufferedReader != null) {
            bufferedReader.close();
		}
	}

}

using cashfree_pg.Client;
using cashfree_pg.Model;


		[Route("api/[controller]")]
    [ApiController]
    public class YourController : ControllerBase
    {
        [HttpPost]
        public async Task<IActionResult> Post()
        {
            // Read the raw body of the POST request
            using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
            {
                string requestBody = await reader.ReadToEndAsync();
                var headers = Request.Headers;
                var signature = headers["x-webhook-signature"];
                var timestamp = headers["x-webhook-timestamp"];

                Cashfree.XClientId = "<x-client-id>";
                Cashfree.XClientSecret = "<x-client-secret>";
                Cashfree.XEnvironment = Cashfree.SANDBOX;
								var cashfree = new Cashfree();

                try {
                var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                } catch(Exception e) {
                // Error if signature mis matches
                }
            }
        }
    }

Manual verification (custom approach)

function verify(ts, rawBody){
    const body = req.headers["x-webhook-timestamp"] + req.rawBody;
    const secretKey = "<your secret key>";
    let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
    return genSignature
}

func VerifySignature(expectedSig string, ts string, body string) (string, error) {
	t := time.Now()
	currentTS := t.Unix()
	if currentTS-ts > 1000*300 {
		return "", errors.New("webhook delivered too late")
	}
	signStr := strconv.FormatInt(ts, 10) + body
	fmt.Println("signing String: ", signStr)
	key := ""
	h := hmac.New(sha256.New, []byte(key))
	h.Write([]byte(signStr))
	b := h.Sum(nil)
	return base64.StdEncoding.EncodeToString(b), nil
}

timestamp := c.Request().Header.Get("x-webhook-timestamp")
body, _ := ioutil.ReadAll(c.Request().Body)
rawBody := string(body)
signature := c.Request().Header.Get("x-webhook-signature")

VerifySignature(signature, timestamp, rawBody)

function computeSignature($ts, $rawBody){
    $rawBody = file_get_contents('php://input');
		$ts = getallheaders()['x-webhook-timestamp'];

    $signStr = $ts . $rawBody;
    $key = "";
    $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
    return $computeSig;
}

public String generateSignature() {

	bufferedReader = request.getReader();
  String line;
  while ((line = bufferedReader.readLine()) != null) {
     stringBuilder.append(line).append('\n');
  }
  String payload = stringBuilder.toString();
  String timestamp = request.getHeader("x-webhook-timestamp");

  String data = timestamp+payload;

  String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
  Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
  SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
  sha256_HMAC.init(secret_key_spec);
  String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
  return computed_signature; // compare with "x-webhook-signature"
}

import base64
import hashlib
import hmac

def generateSignature():
    # Get the raw body from the request
    raw_body = request.data

    # Decode the raw body bytes into a string
    payload = raw_body.decode('utf-8')

    #verify_signature
    timestamp = request.headers['x-webhook-timestamp']

    signatureData = timestamp+payload
    message = bytes(signatureData, 'utf-8')
    secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
    signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
    computed_signature = str(signature, encoding='utf8')
    return computed_signature #compare with "x-webhook-signature"

Webhook migration

Webhook endpoints have a specific API version set, for example 2023-08-01. To migrate from an older version to a newer version, we recommend the following steps:

Add webhook for new version

Create a new webhook endpoint with the new url and new version. Subscribe to the events you want to consume.

Update your code to return 200 for new webhooks

Update your event processing code and return a 200 response to prevent delivery retries. Next, enable the new webhook endpoint that you created in the previous step. At this point every event is sent twice: once with the old API version and once with the new one.

Update your webhook code to process events for the new endpoint

Update your code to ensure you can process the version of your new webhook endpoint. Make sure you read the changelog and handle any breaking changes.

Disable old webhook endpoint

If events aren’t being correctly handled by your new code, first temporarily disable the new webhook endpoint. After monitoring for some time, you can permanently delete the old webhook endpoint.

​Verify webhooks

​Test webhooks

​Retry webhooks policy

​Resend webhooks

​Webhook signature verification

​SDK verification (built-in approach)

​Manual verification (custom approach)

​Webhook migration

Verify webhooks

Test webhooks

Retry webhooks policy

Resend webhooks

Webhook signature verification

SDK verification (built-in approach)

Manual verification (custom approach)

Webhook migration