Skip to main content

​
Introduction to KYC Webhooks

Ripio utilizes webhooks to provide real-time updates on the status of KYC (Know Your Customer) verification processes. By subscribing to these events, your application can stay informed about the progress of customer identity verification and react accordingly. All KYC webhook events share a common payload structure and are sent as POST requests to your configured KYC webhook endpoint. Remember to validate the signature of each incoming webhook as described in the Webhooks Introduction.

​
Event Payload Structure

Each KYC event notification message contains a JSON-formatted payload with the following general structure: 
{
  "eventType": "KYC.COMPLETED",
  "issueDatetime": "2026-03-12T14:22:22.508Z",
  "payload": {
    "submissionId": "9faf77b8-b9ee-4737-9392-6c1b63f0fd21",
    "customerId": "75c741a2-c3c8-46b1-a807-4fa1f4010026",
    "createdAt": "2026-03-12T14:22:22.544453Z",
    "source": "WIDGET",
    "metadata": {}
  }
}
  • eventType (String): The specific type of KYC event that occurred, following the format KYC.<STATUS>.
  • issueDatetime (String): The Coordinated Universal Time (UTC) timestamp indicating when the event was triggered.
  • payload (Object): An object containing details of the KYC submission associated with the event.

​
Payload Fields

The payload object contains the following fields:
  • submissionId (String): Unique identifier for the KYC submission.
  • customerId (String): Unique identifier of the customer associated with the KYC submission.
  • createdAt (String): Date and time the KYC submission was created (UTC).
  • source (String): Origin of the KYC submission. Possible values:
    • "WIDGET" — Submission originated from the Ripio Widget integration.
    • "API" — Submission originated from a direct API integration.
  • metadata (Object): Additional context associated with the submission. May include tracking information such as session identifiers.

​
KYC Event Types

The following event types are available for KYC verification processes:

​
KYC.INCOMPLETE_USER_DATA

  • Description: Sent when a KYC verification process has been initiated but the user’s data is still incomplete. This is typically the first event in the KYC lifecycle.

​
KYC.IN_REVIEW

  • Description: Sent when the KYC submission has been received and is currently under review by the verification provider.

​
KYC.COMPLETED

  • Description: Sent when the KYC verification has been successfully completed and the customer’s identity has been approved.

​
KYC.FAILED

  • Description: Sent when the KYC verification has been rejected. The customer’s identity could not be verified.