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.Tipos de alerta
Payload
Todo alerta é umPOST 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 exemplosession_in_review.labelevalue: o assunto do alerta, por exemploSessione#1042.
data:
alert.billing.autorefill_failedadicionapaused, um booleano que étruequando a recarga automática fica pausada até você atualizar o cartão.alert.service.degradedealert.service.recoveredadicionamservice,status,incident_id,service_name,state,affected,country_name,started_at,resolved_at,duration_minutes,titleebody.statusédegradedoudownemalert.service.degraded, erecoveredemalert.service.recovered.serviceusa as chaves de serviço deGET /v3/status/, eincident_idcorresponde a umidde incidente ali.
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-Timestampesteja 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
400se a verificação falhar. Uma resposta401,403,404ou410marca o destino para reconexão (veja Novas tentativas).
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 resposta2xx.
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
- Webhooks de verificação: resultados de sessões, entidades e transações da sua aplicação.
- Status do serviço: o feed público por trás de
alert.service.degradedealert.service.recovered. - Revisão manual: o que fazer com uma verificação em revisão.