Webhooks - Documentation

Overview

The system sends HTTP webhooks to notify events in the onboarding process. Each event is recorded in the database and dispatched to the configured URL.

Configuration

Onboarding: send webhook_url and, optionally, transaction_id in:
- POST /customer/register
- POST /links/generate
The transaction_id is associated with the onboarding link and is sent as transaction_id in all events for that onboarding (document, selfie, analysis, success/failure).
Liveness: in POST /links/generate with flow=liveness, you can send transaction_id (optional).

This value is stored in the submission of that liveness journey and will be the transaction_id sent in the face_match_start, face_match_success, and face_match_error webhooks for that same journey. The onboarding link and the onboarding transaction_id are not changed.

Events

CPF Pre-registration Check

check_onboarding_start - CPF verification started
check_onboarding_success - CPF verification completed
check_onboarding_error - CPF verification error

Document Upload

front_document_upload_start - Front upload started
front_document_upload_success - Front upload completed
front_document_upload_error - Front upload error
back_document_upload_start - Back upload started
back_document_upload_success - Back upload completed
back_document_upload_error - Back upload error
selfie_upload_start - Selfie upload started
selfie_upload_success - Selfie upload completed
selfie_upload_error - Selfie upload error

Document Analysis

document_analysis_start - Analysis started
document_analysis_success - Analysis completed
document_analysis_error - Analysis error

Onboarding Process

onboarding_succeeded - Onboarding approved
onboarding_failed - Onboarding rejected

Facial Verification

Events (parameter flow: "onboarding" | "liveness" in the payload):

face_match_start - Facial verification (liveness) started
face_match_success - Facial verification approved
face_match_error - Facial verification rejected or error

transaction_id in the payload:

In liveness flow: this is the transaction_id sent when generating the liveness link (POST /links/generate with flow=liveness), when provided; it allows correlating the webhook to that liveness journey.
In onboarding flow: this is the transaction_id associated with the onboarding link (provided in register/generate).

Webhook Payload

All events include:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "nome_do_evento",
  "status_detail": "status_granular",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

The transaction_id field can be null when none was provided in the configuration. In face_match_* events of the liveness flow, the transaction_id is the one provided when generating the liveness link (per journey), when supplied.

`status_detail` Field (Granular Status)

The status_detail field indicates the specific reason for onboarding failure or success. The possible values are:

`status_detail`	Description	Cause
`document_system_error`	OCR system failure (timeout, API error)	Internal error
`invalid_document`	Illegible document or incorrect type	User error
`document_rejected`	Document data does not match (name, CPF, or date of birth)	User error
`liveness_system_error`	Facial verification system failure	Internal error
`liveness_rejected`	Facial similarity below threshold	User error
`approved`	Onboarding approved successfully	Success

The status field (legacy) remains present in payloads with values "approved", "rejected", or "error", maintaining compatibility with existing integrations. Use status_detail to identify the specific cause of failure.

Completion Event (onboarding approved)

When the onboarding is approved, the webhook includes additional data:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "face_match_success",
  "status": "approved",
  "status_detail": "approved",
  "similarity": 0.79,
  "similarity_threshold": 0.67,
  "matches": true,
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

(In liveness flow, transaction_id is the one provided when generating the liveness link for that journey.)

Rejection Event (facial verification)

When facial verification fails, the webhook includes:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "face_match_error",
  "status": "rejected",
  "status_detail": "liveness_rejected",
  "similarity": 0.45,
  "similarity_threshold": 0.67,
  "matches": false,
  "reason": "Similaridade abaixo do threshold",
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

When the failure is due to a system error in facial verification:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "face_match_error",
  "status": "rejected",
  "status_detail": "liveness_system_error",
  "reason": "Failed to compare selfie with portrait",
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

Rejection Event (document analysis)

When document analysis fails due to mismatched data:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "document_analysis_error",
  "status": "rejected",
  "status_detail": "document_rejected",
  "reason": "Dados do documento não conferem",
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

When the failure is due to an illegible document:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "document_analysis_error",
  "status": "rejected",
  "status_detail": "invalid_document",
  "reason": "Documento ilegível ou tipo incorreto",
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

When the failure is due to an OCR system error:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "document_analysis_error",
  "status": "error",
  "status_detail": "document_system_error",
  "reason": "Document verification system error",
  "completed_at": "2026-01-08T14:18:02.584Z",
  "timestamp": "2026-01-08T14:18:07.798Z"
}

Completion Event (liveness approved)

When the liveness facial verification is approved:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid | null",
  "event_type": "face_match_success",
  "status": "approved",
  "status_detail": "approved",
  "similarity": 1,
  "similarity_threshold": 0.67,
  "matches": true,
  "completed_at": "2026-02-23T20:40:13.232Z",
  "timestamp": "2026-02-23T20:42:26.844Z",
  "flow": "liveness"
}

Rejection Event (liveness rejected)

When the liveness facial verification is rejected:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid | null",
  "event_type": "face_match_error",
  "status": "rejected",
  "status_detail": "liveness_rejected",
  "similarity": 0.45,
  "similarity_threshold": 0.67,
  "matches": false,
  "reason": "Similaridade abaixo do threshold",
  "completed_at": "2026-02-23T20:40:13.232Z",
  "timestamp": "2026-02-23T20:42:26.844Z",
  "flow": "liveness"
}

System Error Event (liveness)

When a system error occurs during liveness facial verification:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid | null",
  "event_type": "face_match_error",
  "status": "rejected",
  "status_detail": "liveness_system_error",
  "reason": "Failed to compare selfie with portrait",
  "completed_at": "2026-02-23T20:40:13.232Z",
  "timestamp": "2026-02-23T20:42:26.844Z",
  "flow": "liveness"
}

Rejection fields:

status: "rejected" or "error"
status_detail: Granular status indicating the specific cause (see table above)
similarity: Calculated similarity (0-1) -- present only in facial verification events
similarity_threshold: Configured threshold -- present only in facial verification events
matches: false
reason: Reason for rejection
completed_at: Completion date/time

Rejection types by event:

face_match_error: Facial verification rejection (liveness_rejected or liveness_system_error)
document_analysis_error: Document analysis rejection (document_rejected, invalid_document, or document_system_error)

Expected Response

The endpoint must respond with an HTTP 2xx status to indicate success. Timeout is 30 seconds.

Notes

Webhooks are sent asynchronously
Delivery failures do not interrupt the main flow
All events are recorded in the database
The webhook URL is automatically decoded (supports HTML entities)

How to use the API UX Tips