Webhooks e SDKs
Webhooks notifique o seu back-end sobre eventos de negócio. Utilize-os juntamente com as consultas API para que as entregas atrasadas ou perdidas não deixem os seus registos por resolver.
Verifique antes de processar
A entrega atual inclui X-Webhook-Signature e X-Webhook-Timestamp. A assinatura utiliza HMAC-SHA256 sobre o texto do cabeçalho do carimbo de data/hora, um ponto e o corpo bruto exato do pedido. O seu valor de cabeçalho tem o formato sha256=<HEX_SIGNATURE>.
- Retenha o corpo em bruto antes de analisar JSON.
- Valide o carimbo de data/hora utilizando a tolerância de relógio acordada.
- Verifique a assinatura com o segredo webhook utilizando uma comparação de tempo constante.
- Só depois interprete a carga útil e atualize os registos comerciais.
A reformatação do JSON analisado antes da verificação altera os bytes assinados. A verificação Webhook utiliza o segredo webhook, e não o segredo do pedido API ou a chave de autorização do cliente.
Armazenar e desduplicar
O envelope inclui event_id, event_type, created_at, tenant_id e data. Para entregas de eventos normais, utilize a identidade de evento verificada com o seu endpoint ou contexto de espaço de trabalho para evitar aplicações repetidas. Persista esta decisão de forma atómica com a atualização de negócio resultante ou coloque o evento verificado na fila de forma duradoura antes de o reconhecer.
X-Webhook-Idempotency-Key também é fornecido para entregas normais de caixa de saída. São metadados de entrega, não um campo de carga assinado de forma independente. Não deixe que um cabeçalho alterado faça com que o mesmo evento verificado mova dinheiro duas vezes. As entregas de testes e as operações manuais podem ter identificadores diferentes ou omitir este cabeçalho.
Devolver uma resposta bem-sucedida após aceitar o evento de forma duradoura. Desenhe para duplicados e eventos atrasados ou fora de ordem. O carimbo de data/hora de entrega não é um horário garantido de ocorrência de negócios. Consulte o recurso subjacente quando um evento entra em conflito com um resultado conhecido posterior.
Escolha o pacote de integração
Estes são escopos de implementação de origem, não confirmação da disponibilidade do registo do pacote ou lançamento geral. Obtenha um pacote de versão correspondente e as suas instruções de instalação durante a integração. Outras características podem exigir chamadas diretas API; não infira um cliente API completo a partir da presença de um pacote webhook.
Teste o caminho de receção
Teste uma entrega válida, corpo modificado, assinatura inválida, carimbo de data/hora obsoleto, evento duplicado e reinicialização do recetor. Confirme os acordos de repetição e repetição com o ambiente de integração. A falta de chamadas de retorno deve desencadear a reconciliação, e não um segundo pedido de retirada.