Webhooks
La parte interessante è cosa succede quando la consegna fallisce
Firma, ritentativi, ordine e idempotenza sono l’intero contratto. Un’integrazione che gestisce il percorso felice non è finita: non è nemmeno cominciata.
- Consegna
- Almeno una volta
- Firmato
- Sul corpo grezzo
- Ritentativi
- Backoff esponenziale
Definition
Come funzionano i webhook del passaporto?
CirculeID invia un callback firmato al tuo endpoint quando un passaporto, un evento o una credenziale cambia. La consegna è almeno una volta con backoff esponenziale, quindi i gestori devono verificare la firma, trattare gli identificativi di consegna ripetuti come operazioni nulle e rileggere lo stato corrente tramite l’API prima di agire.
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.
Eventi
A che cosa potete iscrivervi
| 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
Verificate prima di fare il parsing
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);
}Contratto
Che cosa garantisce la piattaforma
Payload firmati
HMAC sul corpo grezzo con un segreto per endpoint, più una marca temporale.
Consegna almeno una volta
La garanzia onesta per un sistema che ritenta. I gestori devono essere idempotenti.
Backoff esponenziale
Ritentato su una finestra estesa, così un breve disservizio non ti costa nulla.
Versione su ogni payload
Ignora una consegna che descrive una versione che hai già superato.
Registro degli errori visibile
Le consegne fallite sono elencate e ripetibili anziché scartate in silenzio.
Sottoscrizioni mirate
Sottoscrivi per tipo di evento, così un endpoint riceve solo ciò su cui agisce.
Risposte
Domande frequenti
Come faccio a sapere che un webhook viene davvero da CirculeID?
Ogni consegna porta una firma sul corpo grezzo della richiesta e una marca temporale. Verifica la firma con il segreto del tuo endpoint prima di fare il parsing, e rifiuta le consegne la cui marca temporale esce dalla tua finestra di tolleranza. Un endpoint che si fida di un payload non verificato è un endpoint a cui chiunque può inviare.
Le consegne sono ordinate?
Per oggetto, per quanto possibile — ma non farci affidamento. Ritentativi e condizioni di rete fanno sì che un evento più vecchio possa arrivare dopo uno più recente. Ogni payload porta la versione dell’oggetto che riflette, quindi un gestore dovrebbe ignorare una consegna che descrive una versione già superata anziché presumere l’ordine di arrivo.
Che cosa succede se il mio endpoint è irraggiungibile?
La consegna viene ritentata con backoff esponenziale su una finestra estesa, e il log degli errori è visibile nel tuo account anziché silenzioso. Scaduta la finestra la consegna è marcata come fallita; la modifica sottostante resta interrogabile tramite l’API, così un’interruzione dei webhook causa un ritardo e non una perdita di dati.
Lo stesso evento può essere consegnato due volte?
Sì, e dovete darlo per scontato. La consegna almeno una volta è la garanzia onesta di qualsiasi sistema che ritenta. Ogni consegna porta un identificatore stabile: il gestore corretto registra quell’identificatore e tratta una ripetizione come operazione nulla — il che rende anche sicuro rieseguire una finestra fallita.
I payload dei webhook vanno considerati il record completo?
Trattate il payload come una notifica e non come la fonte di verità. Vi dice che qualcosa è cambiato e vi dà abbastanza per decidere se vi riguarda; se agite, rileggete lo stato corrente tramite l’API. Così una consegna vecchia o fuori ordine non può scrivere dati superati nel vostro sistema.
Next step
Punta il primo verso un endpoint di test
Sottoscrivi in sandbox, rompi apposta il tuo endpoint e osserva il comportamento di ritentativo e replay prima di farci affidamento.