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

{
  "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": "[email protected]",
    "customer_type": "individual",
    "completed_at": "2026-06-19T10:00:00Z"
  }
}