Webhooks - Documentação

Visão Geral

O sistema envia webhooks HTTP para notificar eventos do processo de onboarding. Cada evento é registrado no banco de dados e disparado para a URL configurada.

Configuração

• Onboarding: envie webhook_url e, opcionalmente, transaction_id em:

  • POST /customer/register
  • POST /links/generate

  O transaction_id fica associado ao link do onboarding e é enviado como transaction_id em todos os eventos desse onboarding (documento, selfie, análise, sucesso/falha).

• Liveness: em POST /links/generate com flow=liveness, você pode enviar transaction_id (opcional).

  Esse valor é gravado na submission daquela jornada de liveness e será o transaction_id enviado nos webhooks face_match_start, face_match_success e face_match_error dessa mesma jornada. O link do onboarding e o transaction_id do onboarding não são alterados.

Eventos

Checagem de pré-registro de CPF

• check_onboarding_start - Início da verificação de CPF
• check_onboarding_success - Verificação de CPF concluída
• check_onboarding_error - Erro na verificação de CPF

Upload de Documentos

• front_document_upload_start - Início do upload da frente
• front_document_upload_success - Upload da frente concluído
• front_document_upload_error - Erro no upload da frente
• back_document_upload_start - Início do upload do verso
• back_document_upload_success - Upload do verso concluído
• back_document_upload_error - Erro no upload do verso
• selfie_upload_start - Início do upload da selfie
• selfie_upload_success - Upload da selfie concluído
• selfie_upload_error - Erro no upload da selfie

Análise de Documento

• document_analysis_start - Início da análise
• document_analysis_success - Análise concluída
• document_analysis_error - Erro na análise

Processo de Onboarding

• onboarding_succeeded - Onboarding aprovado
• onboarding_failed - Onboarding rejeitado

Verificação Facial

Eventos (parâmetro flow: "onboarding" | "liveness" no payload):

• face_match_start - Início da verificação facial (liveness)
• face_match_success - Verificação facial aprovada
• face_match_error - Verificação facial rejeitada ou erro

transaction_id no payload:

• Em fluxo liveness: é o transaction_id enviado ao gerar o link de liveness (POST /links/generate com flow=liveness), quando informado; permite correlacionar o webhook àquela jornada de liveness.
• Em fluxo onboarding: é o transaction_id associado ao link do onboarding (informado no register/generate).

Payload do Webhook

Todos os eventos incluem:

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

O campo transaction_id pode ser null quando nenhum foi informado na configuração. Nos eventos face_match_* do fluxo liveness, o transaction_id é o informado na geração do link de liveness (por jornada), quando fornecido.

Evento de Conclusão (onboarding aprovado)

Quando o onboarding é aprovado, o webhook inclui dados adicionais:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "face_match_success",
  "status": "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"
}

(Em fluxo liveness, transaction_id é o informado ao gerar o link de liveness para essa jornada.)

Evento de Reprovação (onboarding rejeitado)

Quando o onboarding é rejeitado, o webhook inclui:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid",
  "event_type": "face_match_error",
  "status": "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"
}

Evento de Conclusão (liveness aprovado)

Quando a verificação facial do liveness é aprovada:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid | null",
  "event_type": "face_match_success",
  "status": "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"
}

Evento de Reprovação (liveness rejeitado)

Quando a verificação facial do liveness é rejeitada:

{
  "onboarding_id": "uuid",
  "integration_id": "uuid",
  "transaction_id": "uuid | null",
  "event_type": "face_match_error",
  "status": "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"
}

Campos de reprovação:

• status: "rejected"
• similarity: Similaridade calculada (0-1)
• similarity_threshold: Threshold configurado
• matches: false
• reason: Motivo da reprovação
• completed_at: Data/hora da conclusão

Tipos de reprovação:

• face_match_error: Reprovação na verificação facial
• document_analysis_error: Reprovação na análise do documento

Resposta Esperada

O endpoint deve responder com status HTTP 2xx para indicar sucesso. Timeout de 30 segundos.

Observações

• Webhooks são enviados de forma assíncrona
• Falhas no envio não interrompem o fluxo principal
• Todos os eventos são registrados no banco de dados
• A URL do webhook é decodificada automaticamente (suporta HTML entities)