Webhooks das decisões (Standard Webhooks)

O serviço avisa o seu sistema das decisões com webhooks assinados segundo a especificação Standard Webhooks.

Eventos

intent.approved, intent.denied, intent.expired, intent.cancelled. Uma decisão só é enviada depois de o recibo estar assinado.

O corpo traz identificadores, o estado, o resumo do pedido e o recibo assinado, nunca os valores dos campos:

{"type":"intent.approved","eventId":"…","intentId":"…","externalReference":"INV-42",
 "operationType":"invoice.pay","state":"approved","intentDigest":"…",
 "occurredAtEpochSeconds":1800000000,"receipt":{"status":"signed","payload":"…"}}

Como verifico?

Cabeçalhos: webhook-id, webhook-timestamp (segundos Unix) e webhook-signature (v1,<base64 HMAC-SHA-256(segredo, id "." timestamp "." corpo)>). O segredo é o base64 depois de whsec_.

1. Leia os bytes do corpo antes de interpretar o JSON.
2. Recuse um webhook-timestamp a mais de 5 minutos da sua hora.
3. Calcule o HMAC e compare em tempo constante com cada assinatura v1.
4. Elimine duplicados pelo webhook-id: a entrega é "pelo menos uma vez".

Os SDKs fazem isto com verifyWebhook (TypeScript), verify_webhook (Python) e equivalentes.

Entrega e repetições

Responda com um 2xx em 10 segundos. Outras respostas são repetidas 12 vezes com espera exponencial (10 s a duplicar, até uma hora, com variação aleatória) e depois postas de lado.

Configuração

O administrador define o endereço https:// no cliente máquina, em «Gerir» › «Pedidos de terceiros». O servidor só entrega a domínios autorizados pelo operador; sem eles a consola mostra que os webhooks estão indisponíveis.

Boas práticas

Trate o webhook como um aviso: antes de executar a operação, leia GET /v1/intents/{intent_id} e verifique o recibo.