Skip to main content
Event Name: kyc_state_updated
This event is emitted when the overall KYC verification level changes, typically after a verification process is completed, downgraded, or expires.

Event Payload

The webhook payload contains the following structure:

Field Description

string
required
Unique event identifier (UUID)
string
required
Event type - always kyc_state_updated for this webhook
string
required
Event timestamp in ISO 8601 format
object
required
Contains the event data
integer
required
Unique KYC record ID
string
required
Entity type associated with the KYC record. Possible values: user, related-party
string
Unique user ID (UUID)
Unique related party ID (UUID)
string
required
Current KYC level. Common values include REGULAR and LIGHT

When This Event Is Sent

This webhook is sent when the KYC record changes its overall verification level. Typical scenarios include:
  • A verification flow upgrades the entity to REGULAR
  • A review or business rule downgrades the entity to LIGHT
  • A document expiration process updates the KYC level

Expected Responses

Success Response

HTTP 200 OKThe webhook was processed successfully.

Client Error

HTTP 4xx StatusClient-side error. Will not be retried.

Server Error

HTTP 5xx StatusServer-side error. Will be retried with exponential backoff.

Implementation Example