Referência da API de Webhooks do FACEIO

Receba notificações HTTPS POST quando os usuários fizerem cadastro, se autenticarem com o FACEIO ou excluírem um Facial ID. Use webhooks para manter seu backend sincronizado com eventos de autenticação facial sem depender apenas do estado do frontend.

ABRIR o FACEIO Console

Crie ou selecione uma aplicação no FACEIO Console, registre um endpoint HTTPS e obtenha o token de webhook atribuído à aplicação.

Visão geral dos Webhooks do FACEIO

Entrega de eventos no servidor para cadastros, autenticações e exclusões de Facial ID

Os webhooks do FACEIO notificam o backend após um novo cadastro, uma autenticação bem-sucedida ou uma exclusão de Facial ID. Use esses eventos do servidor para conciliar seus registros de conta com a atividade do FACEIO.

Quando um evento é acionado, o FACEIO envia uma requisição HTTPS POST para a URL do endpoint de webhook configurada para sua aplicação. O payload JSON identifica o Facial ID exclusivo, o ID público da aplicação, o nome do evento, o endereço IP do cliente, o timestamp, o payload vinculado quando disponível e detalhes do cadastro, como idade aproximada e gênero.

Use eventos de webhook para atualizar registros do backend, criar uma trilha de auditoria ou acionar seu próprio fluxo no servidor. Valide cada webhook recebido antes de processar o payload e siga as boas práticas de segurança do FACEIO.

Atualizações em tempo real

Receba notificações de eventos quando os usuários fizerem cadastro, se autenticarem ou concluírem a exclusão de um Facial ID.

Sincronização do backend

Atualize os registros internos das contas a partir de eventos confiáveis do servidor, em vez de depender apenas de callbacks do navegador.

Configurar Webhooks do FACEIO

Configure um endpoint de webhook para cada aplicação FACEIO que precise entregar eventos ao backend. Seu endpoint deve aceitar JSON por HTTPS, validar o token do cabeçalho WWW-Authenticate e retornar rapidamente uma resposta de sucesso.

Abrir o FACEIO Console

Entre na sua conta no FACEIO Console ↗.

Abrir o Application Manager

Na tela principal do Console, abra o Application Manager ↗.

Selecionar a aplicação de destino

Escolha a aplicação FACEIO que deve enviar notificações de cadastro, autenticação e exclusão de Facial ID.

Abrir a aba Webhooks

Acesse a aba WEBHOOKS na tela do Application Manager.

Adicionar a URL do endpoint

Informe a URL do endpoint de webhook que receberá os eventos do FACEIO e salve as configurações da aplicação.

✓

Começar a receber eventos

Depois que um evento for acionado, o FACEIO fará uma requisição HTTPS POST para a URL do webhook com o payload JSON descrito abaixo.

Detalhes da requisição HTTP

A URL do seu endpoint de webhook deve processar a requisição HTTPS recebida e iniciada pelo FACEIO sempre que um evento for acionado. O formato da requisição é resumido abaixo.

Método HTTP	POST
Tipo de conteúdo	`application/json`
Payload POST	Objeto JSON. Consulte a seção abaixo para os campos esperados no corpo.
Tempo limite	6 segundos Seu servidor HTTP deve aceitar a requisição POST recebida em menos de 6 segundos. Após esse prazo, o FACEIO encerra a conexão automaticamente.
Cabeçalho WWW-Authenticate O cabeçalho HTTP `WWW-Authenticate` é sempre incluído em cada requisição POST iniciada pelo FACEIO.	Específico para cada aplicação FACEIO Verifique a autenticidade da requisição inspecionando o valor do token Bearer incorporado ao cabeçalho HTTP `WWW-Authenticate`. Ele deve corresponder à chave de token atribuída à sua aplicação. Obtenha essa chave de token no Application Manager no FACEIO Console ↗.

Boas práticas de segurança

Sempre verifique as requisições de webhook recebidas comparando o token do cabeçalho WWW-Authenticate com a chave de token da sua aplicação. Rejeite divergências, processe os eventos de forma idempotente e consulte as boas práticas de segurança antes de usar eventos de webhook em fluxos de autorização de produção.

Corpo da requisição POST

O corpo de cada requisição de webhook recebida pelo FACEIO é um objeto JSON. Use os campos abaixo para identificar o evento, associá-lo à sua aplicação FACEIO e conciliá-lo com seus registros de conta.

webhook-payload.json

{
  "eventName": "String - Nome do evento",
  "facialId": "String - Facial ID exclusivo do usuário de destino",
  "appId": "String - Public ID da aplicação",
  "clientIp": "String - Endereço IP público",
  "payload": "Blob - Dados vinculados ao usuário, se houver (disponível a partir do plano Business)",
  "details": {
    "timestamp": "String opcional - Timestamp do evento",
    "gender": "String opcional - Gênero do usuário cadastrado",
    "age": "String opcional - Idade estimada do usuário cadastrado"
  }
}

Use o valor do token do cabeçalho HTTP WWW-Authenticate, disponível no FACEIO Console ↗, para verificar a autenticidade da requisição.

`eventName`	é o nome do evento que acionou esta requisição.
`facialId`	é o Facial ID exclusivo do usuário que está sendo cadastrado ou autenticado
`appId`	é o ID público da aplicação que acionou esta requisição. Você encontra o ID público de cada aplicação no FACEIO Console ↗.
`clientIp`	é o endereço IP público da sessão do navegador que inicializou `fio.js`. Consulte as boas práticas de privacidade antes de armazenar ou reter dados de IP do cliente.
`payload`	são os dados que você já associou a este usuário, se houver, durante o cadastro. Mantenha os valores do payload no mínimo necessário e evite armazenar segredos ou dados pessoais desnecessários. Os mesmos dados também serão enviados ao seu frontend JavaScript em autenticações futuras do mesmo usuário. O campo `payload` é incluído na chamada de webhook somente se sua aplicação estiver no Business Plan ou superior. Consulte a página de preços para mais informações. Esse campo não é incluído no evento de exclusão de Facial ID `DELETION`.

Campos opcionais (somente cadastro)

Os campos a seguir do corpo JSON são incluídos em eventos de cadastro de novos usuários:

`timestamp`	é a data da operação (UTC) no formato YYYY-MM-DD.
`gender`	Gênero do usuário cadastrado: male ou female.
`age`	Idade aproximada do usuário cadastrado.

Eventos

Cada requisição HTTPS POST enviada ao seu endpoint de webhook é acionada por um dos seguintes eventos do FACEIO. O campo eventName no payload JSON POST contém a chave correspondente.

Nome do evento	Descrição
`ENROLL`	É acionado após um usuário concluir seu cadastro.
`AUTH`	É acionado após um usuário concluir sua autenticação.
`DELETION`	É acionado após a exclusão do Facial ID.

Dicas de implementação

Garanta que seu endpoint de webhook responda em até 6 segundos para evitar timeout.
Sempre valide o token do cabeçalho WWW-Authenticate.
Trate os eventos de webhook de forma assíncrona e idempotente para evitar bloquear sua aplicação.
Registre apenas os metadados necessários para depuração, conciliação e auditoria.
Retorne um código de status 200 OK para confirmar o recebimento do webhook.
Use a REST API quando seu backend precisar verificar ou conciliar o estado do Facial ID após um evento.

Configure Webhooks para seu backend

Registre uma URL de webhook HTTPS no FACEIO Console, valide o token do webhook no servidor e processe eventos de cadastro, autenticação e exclusão de Facial ID no backend.

Ler o guia de integração → Abrir o FACEIO Console

URL de webhook HTTPS

Validação do token de webhook

Sincronização do backend orientada a eventos