Video KYC Webhooks - Cashfree Payments

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_GENERATED`	Cashfree generated the VKYC link for the user.
`VKYC_USER_LINK_EXPIRED`	The VKYC link expired.
`VKYC_USER_AADHAAR_VERIFIED`	Cashfree verified the Aadhaar details.
`VKYC_USER_CALL_SCHEDULED`	Cashfree scheduled the VKYC call for the user.
`VKYC_USER_PRECHECK_FAILED`	Pre-verification checks failed.
`VKYC_USER_CALL_QUEUED`	The user joined and is waiting in the queue for an agent.
`VKYC_USER_CALL_STARTED`	The VKYC call started with an agent.
`VKYC_USER_DROPOFF_FROM_CALL`	The user dropped off from the VKYC call.
`VKYC_USER_CALL_COMPLETED`	The VKYC call completed successfully.
`VKYC_AUDITOR_REVIEW_COMPLETED`	The auditor approved or rejected the VKYC packet.

VKYC_USER_LINK_GENERATED

{
  "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
  }
}

VKYC_USER_LINK_EXPIRED

{
  "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
  }
}

VKYC_USER_CALL_SCHEDULED

{
  "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
  }
}

VKYC_USER_CALL_QUEUED

{
  "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
  }
}

VKYC_USER_CALL_STARTED

{
  "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
  }
}

VKYC_USER_CALL_COMPLETED

{
  "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_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 this feature.

Data object fields

The following table describes the fields returned inside the data object.

Field	Type	Description
`verification_id`	`string`	The unique ID for the VKYC verification request, as provided by you during initiation.
`cf_verification_id`	`string`	The unique ID for the VKYC verification request, generated by Cashfree.
`user_id`	`string`	The user ID provided when initiating Video KYC.
`status`	`string`	The current status of the VKYC request.
`status_code`	`string`	The sub-status providing additional detail about the current state.
`link`	`string`	The URL shared with the user to complete the VKYC process.
`link_expiry`	`string`	The date on which the VKYC link expires.
`meeting_schedule`	`string` or `null`	The scheduled UTC timestamp for the VKYC meeting. Returns `null` if no meeting is scheduled.
`auditor_remarks`	`string` or `null`	Remarks provided by the auditor after reviewing the VKYC session. Returns `null` if not yet reviewed.
`agent_remarks`	`string` or `null`	Remarks provided by the agent at the end of the VKYC call. Returns `null` if the call is not completed.

Important status information

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.

​Webhook signature

​VKYC webhook events

​Webhook payload fields

​Data object fields

​Important status information

Webhook signature

VKYC webhook events

Webhook payload fields

Data object fields

Important status information