🛠️ Identity Verification Webhook

Webhook that notifies you whenever an identity verification process has been completed.
It can indicate either a successful verification (VERIFICATION_IDENTITY_COMPLETED), a failed verification (VERIFICATION_IDENTITY_REJECTED), or when verification data has been updated manually (VERIFICATION_IDENTITY_UPDATED).

Overview

The Identity Verification Webhook notifies your system when an identity verification process finishes.
It includes detailed information about the identity, extracted document data, computed fields (like age), associated files, and any errors or inconsistencies detected during the verification.

All three event types share the same payload structure — the main difference is the status field.

Webhook Trigger

Rillis sends a POST request to your configured webhook URL when the verification process is completed or updated.

Webhook Payload Schema

Parameter	Type	Description
id	String	Unique webhook event identifier.
type	String	Type of the event: `"VERIFICATION_IDENTITY_COMPLETED"`, `"VERIFICATION_IDENTITY_REJECTED"`, or `"VERIFICATION_IDENTITY_UPDATED"`.
timestamp	Number (timestamp)	Timestamp of the webhook event.
data.identity_id	String	Unique identifier of the identity verification.
data.identity	Object	Detailed data extracted from the verified document, including computed fields and file references.
data.flow_instance_id	String	Flow instance ID linked to the verification process.
data.flow_id	String	ID of the flow that includes this verification step.
data.user_id	String	ID of the user associated with the identity verification.
data.status	String	`"APPROVED"`, `"REJECTED"`, `"PENDING_REVIEW"`, or `"UPDATED"`.
data.errors	Array of Objects	Any errors, mismatches, or noteworthy conditions detected during the verification.
data.completed_at	String (ISO date)	When the verification process was completed.
data.metadata	Object	Additional metadata (if any).
data.url	String	Reference URL for the verification process.

Status Differences

VERIFICATION_IDENTITY_COMPLETED: Triggered when the verification is approved.

VERIFICATION_IDENTITY_REJECTED: Triggered when the verification fails due to errors, document issues, or inconsistencies.

VERIFICATION_IDENTITY_UPDATED: Triggered when an identity verification record has been manually edited (e.g., fixing incorrectly extracted data).

Manual Updates for Extracted Data

If the extracted document data has errors (for example, OCR misreads), you can manually update the following fields for the identity:

✅ Editable Fields:

Full Name

First Name

Last Name

Document Number

Document Type

Issuing Country

Date of Birth

Sex

Emission Date

Personal Number

This allows for corrections and ensures that your system reflects accurate identity data.

Example Webhook Payload (`VERIFICATION_IDENTITY_COMPLETED`)

{
  "id": "6824f94f0ac4747b5367057f",
  "type": "VERIFICATION_IDENTITY_COMPLETED",
  "timestamp": 1747253583117,
  "data": {
    "identity_id": "6824f94815f0e8499e51a2ce",
    "identity": {
      "documents": [ { "type": "Documento de Identidad", "steps": [ { "data": { "fullName": { "value": "JUAN MANUEL ORTIZ VARGAS" }, "documentNumber": { "value": "1.032.463.412" }, "dateOfBirth": { "value": "1994-04-23" } } } ] } ],
      "computed": { "age": { "data": "31" }, "isDocumentExpired": { "data": { "Documento de Identidad": true } } },
      "file_references_data": [ { "id": "ce38705e-9fac-41c3-868d-91255710d463", "field_name": "verifi_document", "original_name": "frontal-juan-manuel.jpg", "mime_type": "image/jpeg", "size": 106277 } ]
    },
    "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 (CO).", "severity": "low" },
      { "code": "DOCUMENT_EXPIRED", "description": "Document has already expired.", "severity": "high" }
    ],
    "completed_at": "2025-05-14T20:13:03.097Z",
    "metadata": {},
    "url": "https://webhook.site/44c2ff65-88fb-4241-956b-6e8ad5a0f782"
  }
}

Example Webhook Payload (VERIFICATION_IDENTITY_REJECTED)

{
  "id": "6824f94f0ac4747b5367057f",
  "type": "VERIFICATION_IDENTITY_REJECTED",
  "timestamp": 1747253583117,
  "data": {
    "identity_id": "6824f94815f0e8499e51a2ce",
    "identity": { ... },
    "flow_instance_id": "6824f15c15f0e8499e51a25c",
    "flow_id": "67a3af4ca59af345d61f4f9c",
    "user_id": "67a3a5065eee513d753f19b7",
    "status": "REJECTED",
    "errors": [
      { "code": "DOCUMENT_EXPIRED", "description": "Document has already expired.", "severity": "high" }
    ],
    "completed_at": "2025-05-14T20:13:03.097Z",
    "metadata": {},
    "url": "https://webhook.site/44c2ff65-88fb-4241-956b-6e8ad5a0f782"
  }
}

Example Webhook Payload (VERIFICATION_IDENTITY_UPDATED)

{
  "id": "6824f94f0ac4747b5367057f",
  "type": "VERIFICATION_IDENTITY_UPDATED",
  "timestamp": 1747253583117,
  "data": {
    "identity_id": "6824f94815f0e8499e51a2ce",
    "identity": {
      "documents": [ { "type": "Documento de Identidad", "steps": [ { "data": { "fullName": { "value": "JUAN MANUEL ORTIZ VARGAS (edited)" }, "documentNumber": { "value": "1.032.463.412" }, "dateOfBirth": { "value": "1994-04-23" } } } ] } ],
      ...
    },
    "flow_instance_id": "6824f15c15f0e8499e51a25c",
    "flow_id": "67a3af4ca59af345d61f4f9c",
    "user_id": "67a3a5065eee513d753f19b7",
    "status": "UPDATED",
    "completed_at": "2025-05-14T20:13:03.097Z",
    "metadata": {},
    "url": "https://webhook.site/44c2ff65-88fb-4241-956b-6e8ad5a0f782"
  }
}

Identity Verification

🛠️ Identity Verification Webhook#

Overview#

Webhook Trigger#

Webhook Payload Schema#

Status Differences#

Manual Updates for Extracted Data#

Example Webhook Payload (VERIFICATION_IDENTITY_COMPLETED)#

Example Webhook Payload (VERIFICATION_IDENTITY_REJECTED)#

Example Webhook Payload (VERIFICATION_IDENTITY_UPDATED)#