> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Video KYC Webhooks

> Configure Video KYC webhooks to receive real-time notifications when VKYC verification status changes in your PPI integration.

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.

<Warning>
  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.
</Warning>

## 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                  |

<Tip>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.</Tip>

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

<AccordionGroup>
  <Accordion title="VKYC_USER_LINK_GENERATED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_LINK_EXPIRED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_AADHAAR_VERIFIED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_SCHEDULED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_PRECHECK_FAILED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_QUEUED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_STARTED">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_DROPOFF_FROM_CALL">
    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_COMPLETED">
    ```json theme={"dark"}
    {
      "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"
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_AUDITOR_REVIEW_COMPLETED">
    ```json theme={"dark"}
    {
      "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"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 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](/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions#status-statuscode-mapping) page for a comprehensive list of status and status\_code combinations.

<Note>
  Verifying the signature is mandatory before processing any response. For more information, see [Signature verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification#webhook-signature-verification).
</Note>

<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0 0-2-2H3z" />

      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/video-kyc-verification">Initiate Video KYC API</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/get-video-kyc-status">Get Video KYC Status API</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions">VKYC status and sub-status mapping</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification">Webhook signature verification</a></li>
  </ul>
</div>