Cashfree sends event-based notifications when specific Video KYC events occur. Use these notifications to track the status and progress of VKYC in real time.
Network retries, read timeouts, processing delays, or delivery failures can cause the same webhook to be delivered more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
Webhook signature You receive the webhook signature in the webhook header. The following table shows a sample header from a webhook request.
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
Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising 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.
VKYC webhook events The following events are triggered at different stages of the Video KYC process.
Event Description VKYC_USER_LINK_GENERATEDCashfree generated the VKYC link for the user. VKYC_USER_LINK_EXPIREDThe VKYC link expired. VKYC_USER_AADHAAR_VERIFIEDCashfree verified the Aadhaar details. VKYC_USER_CALL_SCHEDULEDCashfree scheduled the VKYC call for the user. VKYC_USER_PRECHECK_FAILEDPre-verification checks failed. VKYC_USER_CALL_QUEUEDThe user joined and is waiting in the queue for an agent. VKYC_USER_CALL_STARTEDThe VKYC call started with an agent. VKYC_USER_DROPOFF_FROM_CALLThe user dropped off from the VKYC call. VKYC_USER_CALL_COMPLETEDThe VKYC call completed successfully. VKYC_AUDITOR_REVIEW_COMPLETEDThe auditor approved or rejected the VKYC packet.
{ "event_type" : "VKYC_USER_LINK_GENERATED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "RECEIVED" , "status_code" : "LINK_GENERATED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
{ "event_type" : "VKYC_USER_LINK_EXPIRED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "EXPIRED" , "status_code" : "VKYC_EXPIRED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2025-05-22" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
VKYC_USER_AADHAAR_VERIFIED
{ "event_type" : "VKYC_USER_AADHAAR_VERIFIED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "PRE_VIDEO_CALL" , "status_code" : "AADHAAR_VERIFICATION_SUCCESS" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
{ "event_type" : "VKYC_USER_CALL_SCHEDULED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "PRE_VIDEO_CALL" , "status_code" : "USER_MEETING_SCHEDULED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : "2025-05-23T14:30:00Z" , "auditor_remarks" : null , "agent_remarks" : null } }
VKYC_USER_PRECHECK_FAILED
{ "event_type" : "VKYC_USER_PRECHECK_FAILED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "PRE_VIDEO_CALL" , "status_code" : "USER_VIDEO_CHECK_FAILED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
{ "event_type" : "VKYC_USER_CALL_QUEUED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "PRE_VIDEO_CALL" , "status_code" : "USER_QUEUED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
{ "event_type" : "VKYC_USER_CALL_STARTED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "VIDEO_CALL" , "status_code" : "USER_ACCEPTED_MEETING" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
VKYC_USER_DROPOFF_FROM_CALL
{ "event_type" : "VKYC_USER_DROPOFF_FROM_CALL" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "VIDEO_CALL" , "status_code" : "USER_DROPPED_OFF" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : null } }
{ "event_type" : "VKYC_USER_CALL_COMPLETED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "POST_VIDEO_CALL" , "status_code" : "AGENT_APPROVED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : null , "agent_remarks" : "Good to go" } }
VKYC_AUDITOR_REVIEW_COMPLETED
{ "event_type" : "VKYC_AUDITOR_REVIEW_COMPLETED" , "event_time" : "2025-05-22T03:51:14Z" , "data" : { "verification_id" : "TestVkycVerification" , "cf_verification_id" : "8901234567890123458" , "user_id" : "USER827364" , "status" : "AUDITOR_REVIEWED" , "status_code" : "AUDITOR_APPROVED" , "link" : "https://vkyc.cashfree.com/session/abc123" , "link_expiry" : "2026-06-27" , "meeting_schedule" : null , "auditor_remarks" : "Looks Good" , "agent_remarks" : "Good to go" } }
Webhook payload fields The webhook payload contains important metadata in its top-level fields.
Field Type Description event_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 this feature.
Data object fields The following table describes the fields returned inside the data object.
Field Type Description verification_idstringThe unique ID for the VKYC verification request, as provided by you during initiation. cf_verification_idstringThe unique ID for the VKYC verification request, generated by Cashfree. user_idstringThe user ID provided when initiating Video KYC. statusstringThe current status of the VKYC request. status_codestringThe sub-status providing additional detail about the current state. linkstringThe URL shared with the user to complete the VKYC process. link_expirystringThe date on which the VKYC link expires. meeting_schedulestring or nullThe scheduled UTC timestamp for the VKYC meeting. Returns null if no meeting is scheduled. auditor_remarksstring or nullRemarks provided by the auditor after reviewing the VKYC session. Returns null if not yet reviewed. agent_remarksstring or nullRemarks provided by the agent at the end of the VKYC call. Returns null if the call is not completed.
For certain webhook events, specifically VKYC_USER_PRECHECK_FAILED and VKYC_USER_CALL_SCHEDULED, you may encounter more than one status_code value.
See the Status and status-code reference page for a comprehensive list of status and status_code combinations.
Verifying the signature is mandatory before processing any response. For more information, see Signature verification . 
