Webhooks do Identity Link: Eventos do Ciclo de Verificação

Os webhooks permitem que o seu backend receba notificações HTTP em tempo real enquanto uma pessoa avança por uma verificação do Identity Link. Em vez de consultar a API em laço, você registra uma URL e a VU publica um payload JSON assinado sempre que uma etapa é concluída ou falha.

Webhooks fazem parte da API, então exigem plano Premium ou Pro — o mesmo requisito de POST /oauth/token. Veja Planos.

Registrar um endpoint

curl -X POST https://api.identity.vu-one.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/vu",
    "description": "Eventos de verificação em produção"
  }'

O corpo aceita exatamente dois campos: url (obrigatório) e description (opcional). Qualquer outro campo é rejeitado. A chamada responde 201:

{
  "_id": "b6b0a1f2-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "userId": "9f8e7d6c-5b4a-4938-2716-0f5e4d3c2b1a",
  "description": "Eventos de verificação em produção",
  "url": "https://seusite.com/webhooks/vu",
  "createdAt": "2026-08-30T14:02:11.000Z",
  "updatedAt": "2026-08-30T14:02:11.000Z"
}

A resposta não traz segredo algum. A assinatura não é por endpoint: existe um único segredo de assinatura por conta, e todos os endpoints registrados recebem payloads assinados com ele.

Onde fica o segredo de assinatura

O seu webhookSecret é um valor de 256 bits exibido no aplicativo em Configurações → Desenvolvedores, ao lado do Client Id e do Client Secret. O mesmo valor volta em um GET /users/me autenticado. Para rotacioná-lo, use Atualizar nessa tela ou chame:

curl -X PATCH https://api.identity.vu-one.com/api/v1/users/me/webhook-secret \
  -H "Authorization: Bearer <token>"

A resposta traz o novo segredo. A rotação vale imediatamente, então publique o novo valor no seu validador antes de rotacionar, ou aceite uma janela curta de entregas rejeitadas.

Eventos

Doze eventos cobrem o ciclo de vida. started dispara quando a etapa começa, successful quando ela passa e failed quando ela é perdida em definitivo.

Evento	Quando dispara
`verification.started`	O fluxo começou: a pessoa abriu o link e iniciou a operação. Também dispara na ramificação adaptativa de apenas selfie.
`verification.addfront.started`	A frente do documento foi enviada para processamento.
`verification.addfront.successful`	A frente foi capturada e lida com sucesso.
`verification.addfront.failed`	A frente falhou no antispoofing e não restam tentativas.
`verification.addback.started`	O verso do documento foi enviado para processamento.
`verification.addback.successful`	O verso foi capturado e lido com sucesso.
`verification.addback.failed`	O verso falhou no antispoofing e não restam tentativas.
`verification.register.started`	A selfie foi enviada para prova de vida e comparação facial.
`verification.register.successful`	A prova de vida e a comparação facial passaram.
`verification.register.failed`	A prova de vida ou a comparação facial falharam e não restam tentativas.
`verification.successful`	O fluxo inteiro terminou com sucesso.
`verification.failed`	A verificação falhou e não vai se recuperar.

Uma tentativa malsucedida com tentativas restantes não gera webhook: a pessoa apenas é convidada a tentar de novo e remainingRetries cai em um. Os eventos *.failed marcam a tentativa esgotada, que é também o momento em que o link é consumido.

Payload

Todo payload tem o mesmo formato de duas chaves: um type e um objeto data.

{
  "type": "verification.addfront.successful",
  "data": {
    "_verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "_externalUserId": "cliente-12345",
    "_metadata": { "campanha": "quickstart" }
  }
}

_externalUserId e _metadata são copiados do link que originou a verificação. Se o link não tinha externalUserId, o campo chega como string vazia; sem metadata, _metadata é {}.

Geolocalização nos eventos terminais

verification.successful e verification.failed também trazem data.geolocation, quando houve captura de localização. Os eventos intermediários nunca trazem — em verification.started a captura ainda não aconteceu.

{
  "type": "verification.successful",
  "data": {
    "_verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "_externalUserId": "cliente-12345",
    "_metadata": {},
    "geolocation": {
      "ip": "200.45.12.9",
      "country": "BR",
      "city": "São Paulo",
      "subdivisions": "São Paulo",
      "latitude": -23.5505,
      "longitude": -46.6333,
      "deviceLatitude": -23.5509,
      "deviceLongitude": -46.6339,
      "accuracy": 18,
      "accuracyRadius": 5,
      "source": "gps",
      "tier": "precise",
      "capturedAt": "2026-08-30T14:07:52.000Z"
    }
  }
}

Chaves ausentes são omitidas em vez de virem como null, então trate todos os campos como opcionais.

A geolocalização do webhook é um subconjunto. permission e sample são removidos, e os campos antifraude policy, ipDistanceKm e serverIp nunca trafegam por webhook — exatamente como estão ausentes dos endpoints públicos. Se a sua lógica de risco precisa deles, consulte a verificação com um token depois de receber o evento.

Validar a assinatura

A VU assina o payload com HMAC-SHA256 sobre o corpo exato da requisição, usando como chave o webhookSecret da sua conta, e envia o digest hexadecimal no cabeçalho X-Signature-SHA256. Valide contra o corpo bruto. Se você fizer parse e serializar o JSON de novo, os bytes mudam e a comparação quebra.

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use(express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = process.env.VU_WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
  const received = Buffer.from(signature, 'hex');
  const digest = Buffer.from(expected, 'hex');
  return received.length === digest.length && crypto.timingSafeEqual(received, digest);
}

app.post('/webhooks/vu', (req, res) => {
  const signature = req.headers['x-signature-sha256'];
  if (!signature || !verifySignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Responda primeiro, processe depois.
  res.status(200).send('OK');

  const event = JSON.parse(req.body);
  enqueue(event.type, event.data._verificationId, event.data._externalUserId);
});

app.listen(3000);

Entrega e retentativas

As retentativas são propositalmente curtas. A VU faz até 3 tentativas, com 100 ms de intervalo, e para assim que o seu endpoint responde 200, 201, 202 ou 204. Qualquer outra coisa — um 500, um timeout, um redirecionamento — consome uma tentativa. Depois da terceira, o evento é descartado e nunca reenviado.

Esse orçamento é pequeno demais para absorver um handler lento, então:

Responda imediatamente e processe de forma assíncrona. Confirme em poucas centenas de milissegundos e mande o trabalho para uma fila.
Seja idempotente. O mesmo evento pode chegar mais de uma vez, e verification.started é reemitido na ramificação adaptativa em alguns caminhos de retentativa.
Não trate o webhook como única fonte de verdade. Reconcilie com GET /verifications/{id}/status?linkId={linkId} tudo o que tem impacto comercial: uma verificação cujo webhook se perdeu continua com o status correto na API.
Leia o resultado antes que ele expire. Passado o expiresAt da verificação, GET /verifications/{id} responde 410. Em Planos está como essa janela é calculada.

Gerenciar endpoints

Ação	Endpoint	Retorna
Listar todos os endpoints	`GET /webhook-endpoints`	Array de endpoints
Obter um endpoint	`GET /webhook-endpoints/{id}`	Um endpoint
Atualizar um endpoint	`PATCH /webhook-endpoints/{id}`	O endpoint atualizado
Excluir um endpoint	`DELETE /webhook-endpoints/{id}`	`{ "_id": "...", "deleted": true }`

PATCH aceita url e description. Todas as rotas exigem o mesmo token Bearer do resto da API.

As rotas de /webhook-endpoints vivem na mesma URL base de POST /links: https://api.identity.vu-one.com/api/v1. Não há um host separado. Se elas respondem 404 com given resource is not implemented, a rota não correspondeu: verifique a URL base, o path e o método em Erros.

Próximos passos

Leia os dados extraídos da verificação no guia de Resultados KYC.
Entenda como os eventos de prova de vida se mapeiam nos tipos de webhook em Prova de vida.
Consulte os códigos de erro se o registro do webhook falhar na página de Erros.

Primeiros Passos

Conceitos-Chave

Referência

Webhooks do Identity Link: Eventos do Ciclo de Verificação

Registrar um endpoint

Onde fica o segredo de assinatura

Eventos

Payload

Geolocalização nos eventos terminais

Validar a assinatura

Entrega e retentativas

Gerenciar endpoints

Próximos passos

​Registrar um endpoint

​Onde fica o segredo de assinatura

​Eventos

​Payload

​Geolocalização nos eventos terminais

​Validar a assinatura

​Entrega e retentativas

​Gerenciar endpoints

​Próximos passos

Registrar um endpoint

Onde fica o segredo de assinatura

Eventos

Payload

Geolocalização nos eventos terminais

Validar a assinatura

Entrega e retentativas

Gerenciar endpoints

Próximos passos