---
title: "Customer KYC events"
---
Gravv sends a webhook event whenever a customer's KYC verification status changes, so you can react to the outcome without polling.

## Event types

| Event type | When it fires |
| :--- | :--- |
| `customer.kyc.status.pending` | Verification has started and is under review. |
| `customer.kyc.status.completed` | Verification passed. |
| `customer.kyc.status.failed` | Verification did not pass. |

These cover individual KYC (`basic`, `intermediate`, and `advanced`). Business verification (KYB) runs on a separate internal flow and does not emit these customer KYC events.

## Event data

Each event uses the standard [webhook envelope](/platform/webhooks/webhooks-overview). The `event_data` object carries:

| Field | Type | Description |
| :--- | :--- | :--- |
| `customer_id` | string (uuid) | The customer whose KYC status changed. |
| `tenant_id` | string | Your tenant id. |
| `kyc_type` | string | Verification level: `basic`, `intermediate`, or `advanced`. |
| `status` | string | `pending`, `completed`, or `failed`. |
| `customer_email` | string | The customer's email. |
| `customer_type` | string | `individual` or `business`. |
| `completed_at` | string (date-time) | When verification completed. Present on `completed`. |
| `failure_reason` | string | Why verification did not pass. Present on `failed`. |

## Sample

```json title="customer.kyc.status.completed event"
{
  "event_id": "8f1c1b3e-2a4d-4e6f-9c0a-1b2c3d4e5f60",
  "event_type": "customer.kyc.status.completed",
  "event_category": "customer",
  "event_group_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
  "tenant_id": "cd90c45c-fa78-4624-a80a-642be301c812",
  "timestamp": "2026-06-19T10:00:00Z",
  "event_data": {
    "customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
    "tenant_id": "cd90c45c-fa78-4624-a80a-642be301c812",
    "kyc_type": "basic",
    "status": "completed",
    "customer_email": "jane@example.com",
    "customer_type": "individual",
    "completed_at": "2026-06-19T10:00:00Z"
  }
}
```