Webhooks
O interessante é o que acontece quando a entrega falha
Assinatura, repetições, ordem e idempotência são todo o contrato. Uma integração que trata apenas o caminho feliz não está terminada; nem sequer começou.
- Entrega
- Pelo menos uma vez
- Assinado
- Sobre o corpo em bruto
- Repetições
- Recuo exponencial
Definition
Como funcionam os webhooks do passaporte?
A CirculeID envia uma chamada de retorno assinada para o seu endpoint quando um passaporte, evento ou credencial muda. A entrega é pelo menos uma vez com recuo exponencial, pelo que os manipuladores devem verificar a assinatura, tratar identificadores de entrega repetidos como operações nulas e reler o estado atual pela API antes de agir.
Treat a payload as a notification, not as the record. That single habit removes the entire class of bug where a delayed retry overwrites newer data with older data.
Eventos
A que se pode subscrever
| Event | Fires when | Typical handler |
|---|---|---|
| passport.created | A passport is issued against an identifier | Print or encode the data carrier |
| passport.updated | The record changes materially | Re-read state; refresh a cached storefront view |
| event.recorded | An EPCIS event is appended to an object | Advance an internal workflow |
| credential.issued | A supplier signs a claim against your product | Clear the compliance gap for that field |
| credential.revoked | An issuer withdraws a claim | Re-open the gap; review anything that relied on it |
| passport.gap_detected | A delegated act change leaves a field unmet | Raise it to the compliance owner |
Verificação
Verifique antes de analisar
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const [ts, signature] = parseHeader(header);
// Reject replays before doing any work.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${ts}.${rawBody}`) // raw body, exactly as received
.digest();
// Constant-time: a fast reject leaks the signature one byte at a time.
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}Contrato
O que a plataforma garante
Payloads assinados
HMAC sobre o corpo em bruto com um segredo por endpoint, mais uma marca temporal.
Entrega pelo menos uma vez
A garantia honesta para um sistema que repete. Os manipuladores têm de ser idempotentes.
Recuo exponencial
Repetido ao longo de uma janela alargada, para que uma curta indisponibilidade não lhe custe nada.
Versão em cada carga útil
Ignore uma entrega que descreva uma versão que já ultrapassou.
Registo de falhas visível
As entregas falhadas são listadas e podem ser reproduzidas, em vez de descartadas em silêncio.
Subscrições delimitadas
Subscreva por tipo de evento, para que um endpoint receba apenas aquilo sobre o que atua.
Respostas
Perguntas frequentes
Como sei que um webhook veio mesmo da CirculeID?
Cada entrega leva uma assinatura sobre o corpo em bruto do pedido e uma marca temporal. Verifique a assinatura com o segredo do seu endpoint antes de fazer o parsing, e rejeite entregas cuja marca temporal saia da sua janela de tolerância. Um endpoint que confia num payload não verificado é um endpoint para onde qualquer pessoa pode enviar.
As entregas são ordenadas?
Por objeto, na medida do possível — mas não dependa disso. Repetições e condições de rede fazem com que um evento mais antigo possa chegar depois de um mais recente. Cada payload transporta a versão do objeto que reflete, pelo que um manipulador deve ignorar uma entrega que descreva uma versão já ultrapassada em vez de presumir a ordem de chegada.
O que acontece se o meu ponto de extremidade estiver em baixo?
A entrega é repetida com recuo exponencial ao longo de uma janela alargada, e o registo de falhas é visível na sua conta em vez de silencioso. Expirada a janela, a entrega é marcada como falhada; a alteração subjacente continua consultável pela API, pelo que uma indisponibilidade de webhooks causa atraso e não perda de dados.
O mesmo evento pode ser entregue duas vezes?
Sim, e deve partir desse princípio. A entrega pelo menos uma vez é a garantia honesta de qualquer sistema que repete. Cada entrega traz um identificador estável, pelo que o manipulador correto regista esse identificador e trata uma repetição como uma operação nula — o que também torna seguro reprocessar uma janela falhada.
Deve confiar-se no payload de um webhook como registo completo?
Trate a carga útil como uma notificação e não como a fonte de verdade. Ela diz-lhe que algo mudou e dá-lhe o suficiente para decidir se lhe interessa; se agir, releia o estado atual através da API. Assim, uma entrega desatualizada ou fora de ordem não pode escrever dados antigos no seu sistema.
Next step
Aponte o primeiro para um endpoint de teste
Subscreva em sandbox, avarie o seu endpoint de propósito e observe o comportamento de repetição e de reprodução antes de depender dele.