Skip to main content
Webhooks are event-based notifications that are received when specific events related to Video KYC occur. These notifications help you track the status and progress of VKYC in real-time.

​
Add webhooks

Add your webhook URL in our system for us to deliver webhook events. Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.
  1. Log in to the Merchant Dashboard and click Developers.
  2. Click Webhooks listed under the Secure ID card.
  3. Click Add Webhook URL in the Webhook screen.
  4. In the Add Webhook popup, fill in the following information:
    • Webhook URL: Enter the URL in this field.
  5. Click Test & Add Webhook.

​
VKYC webhook events

The following events are triggered at different stages of the Video KYC process:
EventDescription
VKYC_USER_LINK_GENERATEDUser VKYC link has been generated for the user.
VKYC_USER_LINK_EXPIREDUser VKYC link has expired.
VKYC_USER_AADHAAR_VERIFIEDUser’s Aadhaar has been successfully verified.
VKYC_USER_CALL_SCHEDULEDUser VKYC call has been scheduled.
VKYC_USER_PRECHECK_FAILEDUser Pre-verification checks have failed.
VKYC_USER_CALL_QUEUEDUser has joined and is waiting in the queue for an agent.
VKYC_USER_CALL_STARTEDUser VKYC call has started with an agent.
VKYC_USER_DROPOFF_FROM_CALLUser has dropped off from the VKYC call.
VKYC_USER_CALL_COMPLETEDUser VKYC call has been completed successfully.
VKYC_AUDITOR_REVIEW_COMPLETEDTriggered when an auditor approves or rejects a VKYC packet.
{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_AADHAAR_VERIFIED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "PRE_VIDEO_CALL",
    "sub_status": "AADHAAR_VERIFICATION_SUCCESS",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_CALL_SCHEDULED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "PRE_VIDEO_CALL",
    "sub_status": "USER_MEETING_SCHEDULED",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": "2025-05-23T14:30:00Z",
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_PRECHECK_FAILED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "PRE_VIDEO_CALL",
    "sub_status": "USER_VIDEO_CHECK_FAILED",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_CALL_QUEUED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "PRE_VIDEO_CALL",
    "sub_status": "USER_QUEUED",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_CALL_STARTED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "VIDEO_CALL",
    "sub_status": "USER_ACCEPTED_MEETING",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_DROPOFF_FROM_CALL",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "VIDEO_CALL",
    "sub_status": "USER_DROPPED_OFF",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
    "link_expiry": "2025-06-21",
    "recording_link": null,
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": null
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_USER_CALL_COMPLETED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "POST_VIDEO_CALL",
    "sub_status": "AGENT_APPROVED",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/ashortCode",
    "link_expiry": "2025-06-21",
    "recording_link": "https://storage.cashfree.com/vkyc/recordings/test333.mp4",
    "meeting_schedule": null,
    "auditor_remarks": null,
    "agent_remarks": "Good to go"
  }
}

{
  "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
  "event_type": "VKYC_AUDITOR_REVIEW_COMPLETED",
  "event_time": "2025-05-22T03:51:14Z",
  "version": "v1",
  "data": {
    "verification_id": "test333",
    "reference_id": 10449,
    "user_reference_id": 10259,
    "user_id": "test11",
    "status": "AUDITOR_REVIEWED",
    "sub_status": "AUDITOR_APPROVED",
    "vkyc_link": "https://forms.qa.cashfree.net/verification/ashortCode",
    "link_expiry": "2025-06-21",
    "recording_link": "https://storage.cashfree.com/vkyc/recordings/test333.mp4",
    "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.
FieldTypeDescription
signaturestringA Base64-encoded HMAC-SHA256 signature of the payload, generated using a shared client secret.
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).
versionstringIndicates the webhook format being used. Default version is “v1”.
dataobjectContains event-specific details related to this feature.

​
data object fields

FieldTypeDescription
verification_idstringThe unique ID for the VKYC verification request.
reference_idnumberThe internal reference ID for the request.
user_reference_idnumberThe internal reference ID for the user.
user_idstringThe user ID provided when creating the VKYC request.
statusstringThe current status of the VKYC request.
sub_statusstringThe sub-status providing additional detail about the current state.
vkyc_linkstringThe URL shared with the user to complete the VKYC process.
link_expirystringThe date on which the VKYC link expires.
recording_linkstring or nullA link to the VKYC session recording. Returns null until the video call is completed.
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.

​
Important status information

For certain webhook Events, specifically VKYC_USER_PRECHECK_FAILED and VKYC_USER_CALL_SCHEDULED, you may encounter more than one subStatus value. Action: Consult the Status-SubStatus Mapping for a comprehensive list.
Verifying the signature is mandatory before processing any response. Refer to Signature Verification for more details.