Transação

Os webhooks de transação são usados para comunicar atualizações de status da transação entre o cliente e o servidor.

Configurando o webhook

Há duas maneiras de configurar um webhook: vinculando-o a um template de consulta ou inserindo-o diretamente na requisição ao iniciar uma transação. Para configurar a URL padrão do webhook de um template de consulta, navegue até o Templates de consulta menu na CAF Trust Platform e acesse o template desejado e edite o Webhook campo.

• Cada Template de Consulta criado na CAF Trust Platform precisará de uma URL de retorno atribuída para os webhooks. Essa URL pode ser diferente entre os templates ativos ou ser a mesma.
• A URL configurada deve estar pronta para receber uma requisição POST após a execução de um serviço da CAF.
• O /transação o ponto de extremidade do serviço pode receber como parâmetro opcional _callbackUrl com cada transação ou requisição de onboarding. A URL padrão configurada no template de consulta associado será ignorada ao usar este parâmetro em qualquer requisição individual. Para mais detalhes sobre essa substituição, vá para a Página Criar uma transação.

Webhook Tester **** e Request Bin são ferramentas úteis para receber chamadas de webhook. Você pode usá-las para gerar uma URL de webhook e usar essa URL para quaisquer requisições do Postman que exijam que você especifique uma URL de webhook; em seguida, use os sites para inspecionar o conteúdo de quaisquer webhooks recebidos.

Notificações de webhook

Você receberá uma notificação via webhook nos seguintes eventos:

• Nova transação de onboarding web

Especificamente, no onboarding web, uma transação é iniciada quando um usuário conclui o fluxo, e você receberá uma notificação do tipo process_startedIsso significa que os documentos foram capturados e enviados para revisão.

• Enviado para documentscopy

Quando o documento tiver sido enviado para o documentscopy, você receberá uma notificação do tipo documentscopy_requestedO status da transação permanece PROCESSING até que o documentscopy seja concluído.

• Mudança de status

Quando o status da transação mudar, você receberá uma status_updated notificação.

O status de uma transação é definido com base nas validações configuradas no template de consulta.

• Falha na análise do VerifAI Docs com retenção zero

Se sua conta tiver o recurso de retenção zero para erros do VerifAI Docs habilitado, você receberá uma notificação do tipo verifai_docs_error quando a análise do VerifAI Docs da transação falhar. Devido à retenção zero, os arquivos enviados não foram retidos e a análise não será reprocessada: reenvie a transação se quiser uma nova análise. A notificação é enviada apenas uma vez por transação, e o status campo contém o status da transação no momento do envio (PENDING, REPROVED ou outro valor, de acordo com as validações configuradas no template de consulta).

Este evento comunica a decisão de não reter os arquivos, não uma confirmação de que a exclusão já foi concluída. O evento é emitido apenas para contas com o recurso habilitado.

Parâmetros de resposta do webhook

Nome	Tipo	Descrição
type*	String	Tipo do evento (process_started, status_updated, documentscopy_requested ou verifai_docs_error)
report*	String	Identificador do relatório (suporte ao fluxo legado). Se a transação não tiver relatório, o valor será retornado como 000000000000000000000000
uuid*	String	Identificador da transação
status*	String	Status da transação
data*	String	Data em que o webhook é enviado no formato UTC
onboardingId	String	Se disponível, o identificador do link de onboarding usado na captura de dados.
templateId	String	Identificador do template de consulta da transação, se existir
statusReasons	Array	Motivos do status
statusReasons[x].category	String	Categoria do motivo
statusReasons[x].code	String	Código do motivo
statusReasons[x].status	String	Status do motivo: ("VALID", "INVALID")
statusReasons[x].resultStatus	String	Resultado do status: ("APPROVED", "REPROVED", "PENDING")
statusReasons[x].description	String	Descrição do motivo

Exemplo de envio de webhook:

{
  "report": "000000000000000000000000",
  "uuid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "status_updated",
  "status": "APPROVED",
  "date": "2023-08-16T16:27:32.801Z",
  "statusReasons": [
    {
      "category": "VALIDATION",
      "code": "over_18",
      "status": "VALID",
      "resultStatus": "APPROVED",
      "description": "Maior de idade (18 anos)."
    }
  ],
  "templateId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
  "onboardingId": "yyyyyyyyyyyyyyyyyyyyyyyy",
}

{
  "report": "000000000000000000000000",
  "uuid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "verifai_docs_error",
  "status": "PENDING",
  "date": "2026-09-11T14:03:22.801Z",
  "statusReasons": [
    {
      "category": "VALIDATION",
      "code": "verifai_docs_available_analysis",
      "status": "INVALID",
      "resultStatus": "PENDING",
      "description": "Invalidar se não existir documentos disponíveis para análise."
    }
  ],
  "templateId": "xxxxxxxxxxxxxxxxxxxxxxxxx"
}

Tratamento de erros

Se não conseguirmos nos comunicar com o seu webhook, faremos até 5 tentativas em no máximo 5 horas. Durante o intervalo entre as requisições, alterações podem ocorrer no status da transação. Caso as notificações sejam entregues fora de ordem cronológica, o status pode não estar atualizado corretamente. Portanto, a recomendação é considerar o atributo de data e sempre consultar a versão mais recente da transação.