Saltar para o conteúdo principal
Webhooks permitem que sua aplicação receba notificações automáticas quando eventos ocorrem em sua conta Truthlocks — por exemplo, quando uma atestação é emitida, uma chave é rotacionada ou uma verificação falha. Em vez de consultar a API para mudanças, seu servidor recebe uma requisição HTTP POST com os detalhes do evento.

Como funciona

1

Registrar um endpoint

Adicione um endpoint de webhook em Configurações > Webhooks no console do inquilino. Forneça uma URL HTTPS publicamente acessível e escolha quais tipos de evento você deseja receber.
2

Receber eventos

Quando um evento correspondente ocorre, Truthlocks envia uma solicitação HTTP POST para sua URL com uma carga JSON descrevendo o evento.
3

Verificar a assinatura

Cada solicitação inclui uma assinatura HMAC-SHA256 no cabeçalho X-Truthlocks-Signature. Verifique-a usando o segredo do endpoint para confirmar que a solicitação veio da Truthlocks.
4

Responder com 200

Retorne um código de status HTTP 200 para confirmar o recebimento. Se o seu endpoint falhar ou expirar, o Truthlocks tentará novamente com um backoff exponencial.

Tipos de eventos

Os eventos são agrupados em categorias. Você pode se inscrever em eventos individuais ou usar um curinga (attestation.*) para receber todos os eventos em uma categoria.

Filtros curinga

Use category.* para assinar todos os eventos em uma categoria. Por exemplo, attestation.* corresponde a attestation.created, attestation.revoked, attestation.expired e attestation.superseded.

Limites de endpoint por plano

O número de endpoints de webhook que você pode criar depende do seu nível de plano: Precisa de mais endpoints? Entre em contato com seu gerente de conta ou atualize seu plano em Configurações > Faturamento.

Criar um endpoint

  1. No console do inquilino, vá para Configurações > Webhooks.
  2. Clique em Adicionar endpoint.
  3. Digite um nome, sua URL de destino HTTPS e selecione os tipos de evento que deseja receber.
  4. Clique em Criar.
O console exibe seu segredo de endpoint uma vez. Copie-o imediatamente — você não poderá recuperá-lo depois.

Via API

Request
Response

Listar endpoints

Recupere todos os endpoints de webhook para seu locatário:
Request
Consulte a referência completa da API para detalhes da resposta.

Verificando assinaturas

Cada solicitação de webhook inclui um cabeçalho de assinatura para verificação. Sempre verifique as assinaturas antes de processar os eventos. Formato da assinatura:
Onde t é o timestamp Unix e v1 é o resumo hexadecimal HMAC-SHA256. Etapas de verificação:
  1. Extraia t (timestamp) e v1 (assinatura) do cabeçalho.
  2. Rejeite a solicitação se o timestamp tiver mais de 5 minutos.
  3. Concatene {timestamp}.{raw_request_body} para formar a string de assinatura.
  4. Calcule HMAC-SHA256 da string de assinatura usando seu segredo de endpoint.
  5. Compare o resumo calculado com v1 usando uma comparação de tempo constante.
Sempre use uma função de comparação de tempo constante (como crypto.timingSafeEqual ou hmac.compare_digest) para evitar ataques de temporização.

Cabeçalhos da solicitação

Cada entrega de webhook inclui estes cabeçalhos:

Comportamento de nova tentativa

Se o seu endpoint retornar um código de status diferente de 2xx ou não responder em 5 segundos, o Truthlocks tentará novamente a entrega com backoff exponencial: Os atrasos incluem até 30% de jitter. Após 8 tentativas totais (1 inicial + 7 retentativas), a entrega é marcada como falha. Você pode visualizar as tentativas de entrega e os detalhes da falha em Configurações > Webhooks clicando em um endpoint, ou consultá-los via API:
Request
Consulte a referência da API de entregas de lista para detalhes da resposta.

Rotação de segredos

Se o segredo do seu webhook for comprometido, gire-o imediatamente:
  1. No console do inquilino, vá para Configurações > Webhooks e clique no endpoint.
  2. Clique em Rotacionar segredo.
  3. Copie o novo segredo — o segredo antigo para de funcionar imediatamente.
Você também pode girar via API:
Request

Testando webhooks

Envie um evento de teste para verificar se seu endpoint está funcionando:
  1. No console do inquilino, vá para Configurações > Webhooks e clique no endpoint.
  2. Clique em Enviar teste.
  3. Um evento webhook.test é enviado para sua URL usando o pipeline completo de assinatura e entrega.
Via API:
Request
Os campos event_type e payload são opcionais — eles assumem como padrão webhook.test e um payload de status básico se omitidos.

Notificações de sinal de risco

Você pode receber notificações de webhook em tempo real sempre que um sinal de risco for criado por qualquer um dos cinco caminhos de detecção do Anti-Fraud Identity Firewall — ingestão direta, normalização de eventos, varredura de deepfake, detecção de ATO e pontuação de velocidade. Assine risk.signal.* para receber todos os eventos de sinal de risco, ou assine risk.signal.created ou risk.signal.escalated individualmente.

Exemplo de payload

Respondendo a sinais de risco

Use webhooks de sinal de risco para acionar respostas automatizadas — bloquear uma sessão de usuário, notificar sua equipe de segurança ou escalar para um caso de fraude — sem consultar a API.
Os webhooks de sinal de risco são acionados para sinais criados por todos os cinco caminhos de detecção. O campo signal_source no payload informa qual caminho gerou o sinal — external, event_normalization, deepfake, ato ou velocity.

Melhores práticas

Responda aos webhooks rapidamente. Faça seu processamento pesado assincronamente após retornar uma resposta 200 para evitar timeouts e novas tentativas.
  • Verifique cada assinatura. Nunca pule a verificação de assinatura, mesmo em desenvolvimento.
  • Use uma fila de mensagens. Enfileire os eventos recebidos e processe-os em um worker para evitar o bloqueio da resposta HTTP.
  • Lidar com duplicatas. Use o cabeçalho X-Truthlocks-Event-Id para deduplicar eventos em caso de novas tentativas.
  • Monitorar falhas de entrega. Verifique a aba de entregas no console regularmente para entregas falhas ou mortas.
  • Mantenha os segredos seguros. Armazene seu segredo de webhook em variáveis de ambiente, não no código-fonte.