Pular para o conteúdo principal
Os webhooks de alertas enviam os alertas da sua equipe para um endpoint HTTPS que você controla. Use-os para alimentar uma ferramenta de plantão, uma fila de tickets ou o seu próprio painel de operações. Os webhooks de alertas são separados dos webhooks de verificação. Os webhooks de verificação enviam os resultados de sessões, entidades e transações para a sua aplicação. Os webhooks de alertas avisam a sua equipe de que algo precisa de atenção: uma verificação aguardando revisão, um pagamento que falhou, um incidente no serviço. Eles têm o próprio payload, segredo de assinatura, assinatura e cronograma de novas tentativas.

Configurar um destino

Você configura os webhooks de alertas no Business Console, não pela API. Os membros que podem gerenciar as configurações da organização podem adicionar, alterar e testar destinos.
1

Adicione o destino

Em Configurações da organização > Notificações da equipe, adicione um destino Webhook de alertas com a URL do seu endpoint. A URL deve usar https:// e ser resolvida para um endereço público.
2

Guarde o segredo de assinatura

A Didit mostra o segredo de assinatura completo, que começa com whsec_, apenas uma vez. Guarde-o agora: depois disso, o console mostra apenas os quatro últimos caracteres.
3

Encaminhe alertas para ele

Adicionar um destino ainda não envia nada para ele. Adicione o destino às regras de encaminhamento dos alertas que você quer que ele receba.
4

Envie um teste

Clique em Enviar teste para enviar um alerta alert.test e confira se o seu endpoint o aceita.
Uma organização pode ter até 25 destinos em Notificações da equipe. Somente a atividade do ambiente de produção chega a um destino. Alertas sobre verificações no sandbox, verificações de empresas, transações e ocorrências AML nunca são enviados a ele.

Tipos de alerta

Payload

Todo alerta é um POST com corpo JSON. A Didit envia o corpo como JSON compacto, com as chaves em ordem alfabética. Este exemplo está formatado para facilitar a leitura:
data sempre contém:
  • event: a chave do evento, por exemplo session_in_review.
  • label e value: o assunto do alerta, por exemplo Session e #1042.
Alguns tipos de alerta adicionam chaves a data:
  • alert.billing.autorefill_failed adiciona paused, um booleano que é true quando a recarga automática fica pausada até você atualizar o cartão.
  • alert.service.degraded e alert.service.recovered adicionam service, status, incident_id, service_name, state, affected, country_name, started_at, resolved_at, duration_minutes, title e body. status é degraded ou down em alert.service.degraded, e recovered em alert.service.recovered. service usa as chaves de serviço de GET /v3/status/, e incident_id corresponde a um id de incidente ali.
Os alertas nunca incluem dados pessoais nem dados de documentos do usuário final. Eles identificam uma sessão, transação ou outro item pelo número e apontam para ele no console. Ignore valores de webhook_type e chaves de data que você não reconhecer, para que novos valores não quebrem o seu endpoint.

Cabeçalhos da requisição

Verificar a assinatura

X-Signature-V2 é o HMAC-SHA256 codificado em hexadecimal da string <X-Timestamp>.<raw body>, usando como chave o segredo de assinatura do seu destino.
  • Use o segredo completo exatamente como a Didit o mostrou, incluindo o prefixo whsec_.
  • Assine os bytes brutos da requisição exatamente como você os recebeu. Fazer o parse do JSON e serializá-lo de novo pode alterar os bytes e invalidar a verificação.
  • Compare as assinaturas em tempo constante.
  • Rejeite uma requisição cujo X-Timestamp esteja a mais de 5 minutos do seu relógio. A Didit assina cada tentativa, incluindo cada nova tentativa, com um timestamp novo, então essa janela nunca rejeita uma nova tentativa legítima.
  • Responda com 400 se a verificação falhar. Uma resposta 401, 403, 404 ou 410 marca o destino para reconexão (veja Novas tentativas).
Os webhooks de alerta não são assinados como os webhooks de verificação. O cabeçalho também se chama X-Signature-V2, mas a string assinada é diferente, e os webhooks de alerta não enviam X-Signature nem X-Signature-Simple. Não reutilize o verificador dos seus webhooks de verificação.

Node.js (Express)

Python (Flask)

Rotacionar o segredo de assinatura

Você rotaciona o segredo do destino em Team notifications. A Didit mostra o novo segredo uma única vez e assina com ele todas as tentativas seguintes, incluindo as novas tentativas de alertas criados antes da rotação. O segredo antigo deixa de funcionar imediatamente. Não há período de sobreposição, e nenhum cabeçalho traz uma assinatura feita com o segredo anterior. Implante o novo segredo no seu endpoint assim que fizer a rotação.

Novas tentativas

A Didit considera entregue qualquer resposta 2xx. Cada tentativa espera até 5 segundos pela sua resposta e não segue redirecionamentos. A Didit tenta novamente enviar um alerta após um timeout, uma falha de conexão, uma resposta 5xx ou uma resposta 408, 425 ou 429. Ela tenta novamente até 5 vezes, ao longo de cerca de 24 horas: Qualquer outra resposta é definitiva, incluindo 3xx e qualquer outro 4xx. Um teste enviado com Send test é enviado uma única vez e nunca é reenviado. Uma resposta 401, 403, 404 ou 410 também marca o destino para reconexão: o console o exibe com o status Reconnect. O mesmo acontece com uma URL que, no momento do envio pela Didit, é resolvida para um endereço privado ou bloqueado por outro motivo. A Didit continua enviando novos alertas ao destino, e ele volta a ficar ativo após a próxima entrega bem-sucedida ou quando você atualiza a URL dele. Recent notifications, em Team notifications, lista cada entrega com o resultado, e você pode tentar novamente uma entrega que falhou a partir dali.

Relacionados

Última modificação em 1 de novembro de 2026