Identity Verification by Onboarding

This document covers the webhook events triggered when an identity verification is completed as part of an onboarding process (like registering shareholders during a company's onboarding). It applies to both cases: approved and rejected.

Overview

The webhook informs your system when an identity verification tied to an onboarding form is completed. The main difference between the two events lies in the status field:

"APPROVED" for successful verifications.

"REJECTED" for unsuccessful verifications.

The rest of the payload structure remains consistent.

Webhook Trigger

Rillis sends a POST request to your configured webhook endpoint each time this type of verification is completed.

Webhook Payload Schema

Parameter	Type	Description
id	String	Unique webhook event identifier.
type	String	Event type: `"VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_COMPLETED"` or `"VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_REJECTED"`.
timestamp	Number (timestamp)	Timestamp of the event.
data.identity_id	String	Unique identifier of the identity verification.
data.identity	Object	Full details of the verified identity.
data.flow_instance_id	String	ID of the flow instance associated with this verification.
data.flow_id	String	ID of the flow.
data.user_id	String	ID of the user associated with this identity verification.
data.status	String	`"APPROVED"` or `"REJECTED"`.
data.errors	Array of Objects	List of errors or inconsistencies detected during the verification.
data.completed_at	String (ISO date)	When the verification was completed.
data.metadata	Object	Additional metadata.
data.url	String	Reference URL for the verification details.

Status Differences

VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_COMPLETED: Triggered when the identity verification linked to an onboarding form is successfully approved.

VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_REJECTED: Triggered when the identity verification linked to an onboarding form is explicitly rejected.

Example Webhook Payloads

Example: Identity Verification by Onboarding Form - Completed

{
  "id": "6824f94c0ac4747b5367057b",
  "type": "VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_COMPLETED",
  "timestamp": 1747253580450,
  "data": {
    "identity_id": "6824f94815f0e8499e51a2e4",
    "identity": { /* identity data... */ },
    "flow_instance_id": "6824f15c15f0e8499e51a25c",
    "flow_id": "67a3af4ca59af345d61f4f9c",
    "user_id": "67a3a5065eee513d753f19b7",
    "status": "APPROVED",
    "errors": [
      {
        "code": "IP_COUNTRY_MISMATCH",
        "description": "Inconsistency between user IP address country (VE) and document country (CL).",
        "severity": "low",
        "confidence": 1,
        "decision": "accept"
      }
    ],
    "completed_at": "2025-05-14T20:13:00.426Z",
    "metadata": {},
    "url": "https://webhook.site/44c2ff65-88fb-4241-956b-6e8ad5a0f782"
  }
}

Example: Identity Verification by Onboarding Form - Rejected

{
  "id": "6824f94c0ac4747b5367057b",
  "type": "VERIFICATION_IDENTITY_BY_ONBOARDING_FORM_REJECTED",
  "timestamp": 1747253580450,
  "data": {
    "identity_id": "6824f94815f0e8499e51a2e4",
    "identity": { /* identity data... */ },
    "flow_instance_id": "6824f15c15f0e8499e51a25c",
    "flow_id": "67a3af4ca59af345d61f4f9c",
    "user_id": "67a3a5065eee513d753f19b7",
    "status": "REJECTED",
    "errors": [
      {
        "code": "IP_COUNTRY_MISMATCH",
        "description": "Inconsistency between user IP address country (VE) and document country (CL).",
        "severity": "low",
        "confidence": 1,
        "decision": "accept"
      }
    ],
    "completed_at": "2025-05-14T20:13:00.426Z",
    "metadata": {},
    "url": "https://webhook.site/44c2ff65-88fb-4241-956b-6e8ad5a0f782"
  }
}

Identity Verification by Onboarding

Overview#

Webhook Trigger#

Webhook Payload Schema#

Status Differences#

Example Webhook Payloads#

Example: Identity Verification by Onboarding Form - Completed#