Webhooks
L’intéressant, c’est ce qui se passe quand la livraison échoue
Signature, reprises, ordre et idempotence forment tout le contrat. Une intégration qui gère le cas nominal n’est pas finie ; elle n’a pas commencé.
- Livraison
- Au moins une fois
- Signé
- Sur le corps brut
- Reprises
- Temporisation exponentielle
Definition
Comment fonctionnent les webhooks de passeport ?
CirculeID envoie un rappel signé à votre point de terminaison lorsqu’un passeport, un événement ou une attestation change. La livraison est au moins une fois avec temporisation exponentielle : vos gestionnaires doivent donc vérifier la signature, traiter les identifiants de livraison répétés comme sans effet, et relire l’état courant via l’API avant d’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.
Événements
Ce à quoi vous pouvez vous abonner
| 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 |
Vérification
Vérifier avant d’analyser
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);
}Contrat
Ce que la plateforme garantit
Charges utiles signées
HMAC sur le corps brut avec un secret par point de terminaison, plus un horodatage.
Livraison au moins une fois
La garantie honnête pour un système qui réessaie. Les gestionnaires doivent être idempotents.
Temporisation exponentielle
Repris sur une fenêtre étendue, si bien qu’une courte panne ne vous coûte rien.
Version sur chaque charge utile
Ignorez une livraison décrivant une version que vous avez déjà dépassée.
Journal des échecs visible
Les livraisons en échec sont listées et rejouables plutôt que perdues en silence.
Abonnements ciblés
Abonnez-vous par type d’événement, pour qu’un point de terminaison ne reçoive que ce sur quoi il agit.
Réponses
Questions fréquentes
Comment savoir qu’un webhook vient bien de CirculeID ?
Chaque livraison porte une signature sur le corps brut de la requête et un horodatage. Vérifiez la signature avec le secret de votre point de terminaison avant de parser, et rejetez les livraisons dont l’horodatage sort de votre fenêtre de tolérance. Un point de terminaison qui fait confiance à une charge non vérifiée est un point de terminaison auquel n’importe qui peut poster.
Les livraisons sont-elles ordonnées ?
Par objet, au mieux — mais n’en dépendez pas. Reprises et conditions réseau font qu’un événement plus ancien peut arriver après un plus récent. Chaque charge utile porte la version d’objet qu’elle reflète : un gestionnaire doit donc ignorer une livraison décrivant une version déjà dépassée plutôt que de présumer l’ordre d’arrivée.
Que se passe-t-il si mon point de terminaison est indisponible ?
La livraison est retentée avec temporisation exponentielle sur une fenêtre étendue, et le journal d’échecs est visible dans votre compte plutôt que silencieux. Passée la fenêtre, la livraison est marquée en échec ; le changement sous-jacent reste interrogeable via l’API, si bien qu’une panne de webhook cause un retard et non une perte de données.
Un même événement peut-il être livré deux fois ?
Oui, et vous devez le supposer. La livraison au moins une fois est la garantie honnête de tout système qui réessaie. Chaque livraison porte un identifiant stable : le bon gestionnaire enregistre cet identifiant et traite une répétition comme sans effet — ce qui rend aussi sûr le rejeu d’une fenêtre en échec.
Faut-il traiter la charge utile d’un webhook comme l’enregistrement complet ?
Traitez la charge utile comme une notification et non comme la source de vérité. Elle vous indique que quelque chose a changé et vous en donne assez pour décider si cela vous concerne ; si vous agissez, relisez l’état courant via l’API. Ainsi, une livraison périmée ou désordonnée ne peut pas écrire d’anciennes données dans votre système.
Next step
Pointez le premier vers un point de terminaison de test
Abonnez-vous en bac à sable, cassez votre point de terminaison exprès, et observez le comportement de reprise et de rejeu avant de vous y fier.