Skip to main content

​
Configure webhook

To configure the webhook, go to Partner Dashboard > Developers > Webhooks. Add your webhook endpoint where you want to receive alerts. Ensure you do not process duplicate events. Webhook will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type. We support webhooks in both encoded and JSON formats. The following are the webhook header parameters and their corresponding descriptions:
ParameterDescription
x-cashfree-timestampTimestamp in ISO format. Time at which the webhook is triggered.
x-cashfree-signatureString. It is a base64 encoded entity of the hash (SHA256) of the raw payload sorted by alphabetical order of keys and the latest partner API key. This signature should be used to verify authenticity of the webhook.

​
Webhook event

The following is the webhook event type and its corresponding description:
Event typeDescription
MERCHANT_ONBOARDING_STATUSTriggered when the merchant’s onboarding status changes (e.g., email verified, KYC approved, account activated).

​
Sample webhook events

The following is an example of a webhook event that you may receive: 
{
   "type":"MERCHANT_ONBOARDING_STATUS",
   "event_time":"2006-01-02T15:04:05Z",
   "data":{
        "merchant_id": "CF89797",
        "merchant_name": "Business A",
        "created_at": "2021-06-23T23:15:20+05:30",
        "onboarding_status": "ACTIVE"
    }
}

​
Webhook payload fields

The following are the webhook payload fields and their corresponding descriptions:
FieldTypeDescription
typestringIndicates the type of event that triggered the webhook.
event_timestringThe UTC timestamp of when the event occurred, formatted in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
dataobjectContains event-specific details related to merchant onboarding.
The following are the webhook parameters and their corresponding descriptions:
ParameterDescription
data.merchant_idUnique merchant ID provided by the partner at the time of merchant creation.
data.merchant_nameName of the merchant.
data.created_atTimestamp in ISO format for when the merchant was created in CF system.
data.onboarding_statusOnboarding status for the merchant.
event_timeTimestamp in ISO format. Time when event was created.
typeType of webhook. Value is “MERCHANT_ONBOARDING_STATUS”.
versionVersion of webhook. Default is 1.

​
Webhook signature

The following is a sample header from a webhook request containing the signature:
Header nameHeader value
content-length1099
x-webhook-attempt1
content-typeapplication/json
x-webhook-signature07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI=
x-webhook-timestamp1746427759733
x-webhook-version2025-01-01
Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or null handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.

​
Verify signature

Use the signature received in webhooks to verify if the request has not been tampered. This is generally a good security practice to avoid abuse via a fraudulent party. To verify the signature at your end, you need your Cashfree Partner API Key along with the webhook object.
  • The timestamp is present in the webhook object header x-webhook-timestamp.
  • The actual signature generated by Cashfree is present in the webhook object header x-webhook-signature.
The signature creation logic is as below:
Signature
timestamp := 1617695238078; 
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $partnerApiKey));

​
Activation lifecycle

The following are the status stages included in the merchant onboarding process:
  1. Pending Email verification: The merchant must first verify their registered Email address. An Email is sent automatically from Cashfree Payments to the merchant Email ID you specified when you added the merchant details. If the merchant has not received the Email in their primary inbox, please ask them to check the spam folder. If the merchant still has not received the Email, you can use the resend Email option or contact the support form for further assistance.
  2. Email verified: This means that the merchant has verified their Email address and can now start their KYC verification process.

​
KYC status

The following are the status stages involved in the merchant KYC process:
  1. Min KYC Pending: Merchant must submit the required KYC details and documents.
  2. Min KYC Submitted: Merchant has submitted their KYC details and documents and the documents are being reviewed by Cashfree Payments.
  3. Min KYC Rejected: Merchant KYC has discrepancies and corresponding KYC details and documents need to be provided.
  4. Min KYC Approved: Merchant KYC has been approved and Payment Gateway product is activated.
If the merchants have verified their email you can fill out the KYC on behalf of the merchant and activate the account for your merchants.