Onboarding Webhooks | Cashfree Payments

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:

Parameter	Description
x-cashfree-timestamp	Timestamp in ISO format. Time at which the webhook is triggered.
x-cashfree-signature	String. 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 type	Description
`MERCHANT_ONBOARDING_STATUS`	Triggered 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:

Field	Type	Description
`type`	`string`	Indicates the type of event that triggered the webhook.
`event_time`	`string`	The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`data`	`object`	Contains event-specific details related to merchant onboarding.

The following are the webhook parameters and their corresponding descriptions:

Parameter	Description
data.merchant_id	Unique merchant ID provided by the partner at the time of merchant creation.
data.merchant_name	Name of the merchant.
data.created_at	Timestamp in ISO format for when the merchant was created in CF system.
data.onboarding_status	Onboarding status for the merchant.
event_time	Timestamp in ISO format. Time when event was created.
type	Type of webhook. Value is “MERCHANT_ONBOARDING_STATUS”.
version	Version of webhook. Default is 1.

Webhook signature

The following is a sample header from a webhook request containing the signature:

Version (2025-01-01)
Version (Legacy)

Header name	Header value
content-length	1099
x-webhook-attempt	1
content-type	application/json
x-webhook-signature	07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI=
x-webhook-timestamp	1746427759733
x-webhook-version	2025-01-01

Header name	Header value
x-cashfree-timestamp	2021-04-16T14:10:36+05:30
x-cashfree-signature	07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI=

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:

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.
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:

Min KYC Pending: Merchant must submit the required KYC details and documents.
Min KYC Submitted: Merchant has submitted their KYC details and documents and the documents are being reviewed by Cashfree Payments.
Min KYC Rejected: Merchant KYC has discrepancies and corresponding KYC details and documents need to be provided.
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.

Platform APIs

v2023-08-01

Webhooks

Configure webhook

Webhook event

Sample webhook events

Webhook payload fields

Webhook signature

Verify signature

Activation lifecycle

KYC status

​Configure webhook

​Webhook event

​Sample webhook events

​Webhook payload fields

​Webhook signature

​Verify signature

​Activation lifecycle

​KYC status

Configure webhook

Webhook event

Sample webhook events

Webhook payload fields

Webhook signature

Verify signature

Activation lifecycle

KYC status