# Documentação de Integração WebHook - Liveness 2.0

# Visão Geral

Esta documentação descreve o processo de integração do autorizador com o WebHook do componente de verificação do Liveness 2.0 da BioDoc. O autorizador será responsável por gerar tokens de autenticação para seus clientes e configurar um listener para receber eventos do POST-event do WebHook.

# 1. Configuração do WebHook

O parâmetro Integração via WebHook será informado pelo cliente no painel de configurações da empresa e ficará disponível para parametrização quando o Liveness 2.0 for ativado.

  • Quando o WebHook estiver habilitado, o fluxo de comunicação utilizará essa URL.

  • Se estiver desabilitado, o fluxo seguirá pelo parâmetro URL (enviado como querystring na abertura do frame).

# 2. Autenticação

Cada operadora pode adicionar um token de acesso, gerado e armazenado na plataforma BioDoc quando o WebHook for ativado no painel de configurações. Esse token deve ser disponibilizado pelo autorizador da operadora cliente, para caso seja implementado essa forma adicional de segurança.

Esse token é opcional e será utilizado na autenticação da requisição enviada à URL configurada, garantindo segurança na comunicação.

# 2.1. Estrutura do Token

  • O token deve ser uma string única gerada pelo autorizador.

  • Deve ser armazenado pelo autorizador de forma segura.

  • O cliente deve poder visualizar o token em seu painel, mas sempre mascarado no campo Token para autenticação do Webhook no painel de configurações.

# 3. Configuração do Listener para Receber o WebHook

O autorizador deve disponibilizar um endpoint HTTP para receber os eventos do WebHook enviados pelo sistema da BioDoc.

# 3.1. Endpoint esperado

Campo Detalhe
Método POST
URL Definida pelo autorizador (deve ser informada no campo URL de comunicação do WebHook no painel de configurações da empresa)
Cabeçalho Authorization: Bearer <TOKEN_DO_CLIENTE>
Content-Type: application/json

# 3.2. Corpo da Requisição (Payload JSON)

A BioDoc enviará um payload JSON com os seguintes dados:

{
  "confidence": "98",
  "date": "2025-02-04T12:34:56Z",
  "response": 200,
  "message": "Liveness verificado com sucesso",
  "card": "1234567890",
  "image": "URL para download da imagem",
  "Success": true,
  "LogID": "b6f2e300-123b-4b7d-bfa0-6ce5a2b86cd1"
}

# 3.3. Validação da Requisição

  • O autorizador deve validar o token presente no cabeçalho Authorization.

  • Caso o token seja inválido ou inexistente, a requisição não deve ser enviada.

  • Se Integração via WebHook estiver ativado e o token for inválido ou inexistente, a requisição deve ser rejeitada com status 401 Unauthorized.

# 3.4. Respostas Esperadas (Status HTTP)

Status HTTP Descrição
200 OK Requisição processada com sucesso

# 3.5. Códigos de Resposta da Operação (Campo response no Payload)

Estes são os códigos que podem ser retornados no campo "response" do payload JSON, indicando o resultado da operação de Liveness:

Código Mensagem
200 'Face Reconhecida'
201 'Cadastro realizado com sucesso!'
202 'Alteração de foto solicitada com sucesso!'
203 'Validação mediante Justificativa: [justificativa]'
400 'Face não reconhecida.'
401 'Face não reconhecida.'

# 4. Fluxo de Operação

  1. O cliente do autorizador inicia a verificação no Liveness 2.0.

  2. A BioDoc envia o resultado da verificação para a Integração via WebHook informada.

  3. O autorizador recebe o POST-event e valida o token de autenticação.

  4. O autorizador processa os dados e encerra a sessão de verificação conforme sua lógica interna.

# 5. Considerações Finais

  • O campo Integração via WebHook é opcional, mas caso ativado, a resposta do Liveness 2.0 será enviada para ele, substituindo o callback padrão.

  • O autorizador deve garantir alta disponibilidade do seu listener para evitar perda de eventos.

  • Recomendamos a implementação de logs e monitoramento para identificar eventuais falhas na comunicação.

  • Se Integração via WebHook estiver ativado, o callback para URL não será acionado.

  • Definir um timeout na requisição para evitar travamentos caso a URL configurada esteja indisponível.

  • Caso haja dúvidas sobre a implementação, entre em contato com nosso suporte técnico.

← BioDoc Liveness →