Ir para a navegação

Webhooks e SDKs

Ver como Markdown

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>.

  1. Retenha o corpo em bruto antes de analisar JSON.
  2. Valide o carimbo de data/hora utilizando a tolerância de relógio acordada.
  3. Verifique a assinatura com o segredo webhook utilizando uma comparação de tempo constante.
  4. 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

Família de pacotesÂmbito de implementação atual
Vá e Python API SDKsEndereço, recursos de depósito e levantamento, assinatura de pedido e ajudantes relacionados
Vá, ajudantes Node.js e Python webhookWebhook verificação de assinaturas e auxiliares de integração de estruturas

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.