Événements webhook et vérification de signature
Chaque événement envoyé par DPP Shield, le format de livraison, la vérification de la signature, et le fonctionnement des nouvelles tentatives et des rejeux.
Équipe éditoriale DPP Shield · Mis à jour:
Un webhook envoie en POST le corps JSON {event, payload, deliveredAt} à votre adresse HTTPS et le signe dans l'en-tête x-dpp-signature : sha256= suivi du HMAC-SHA256 hexadécimal du corps brut avec votre secret de signature. Vérifiez la signature, répondez rapidement en 2xx, et rejouez depuis le journal de livraison ce qui a échoué.
Créer un webhook
- Ouvrez Settings, Webhooks (propriétaires et administrateurs).
- Saisissez l'adresse HTTPS de votre récepteur.
- Choisissez les événements utiles ; sans sélection, il reçoit tous les événements.
- Saisissez un secret de signature d'au moins 16 caractères, ou laissez vide pour que DPP Shield en génère un. Copiez-le : il n'est affiché qu'une fois.
- Surveillez le journal de livraison pour les premiers événements réels.
À quoi ressemble une livraison
Chaque livraison est un POST HTTP avec Content-Type application/json et le corps {"event": "dpp.published", "payload": {…}, "deliveredAt": "2026-10-08T09:30:00.000Z"}. Le payload dépend de l'événement : lisez d'abord le nom de l'événement. Les livraisons de cycle de vie et EPCIS portent l'événement objet EPCIS standard dans le payload.
Vérifier la signature
En Node.js, la valeur attendue est "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"). Analyser puis resérialiser le JSON change les octets et fausse la comparaison : signez toujours le corps brut. Une nouvelle tentative ou un rejeu peut livrer le même événement deux fois : rendez votre traitement idempotent, par exemple par passeport et version.
- Lisez le corps brut de la requête avant toute analyse JSON.
- Calculez le HMAC-SHA256 de ce corps brut avec votre secret et encodez-le en hexadécimal.
- Comparez sha256= suivi de votre résultat avec l'en-tête x-dpp-signature, avec une comparaison à temps constant.
- Refusez la requête s'ils diffèrent ; sinon répondez 2xx et traitez l'événement.
Nouvelles tentatives, journal de livraison et rejeu
Une livraison en échec - erreur réseau ou réponse non 2xx - est retentée jusqu'à cinq fois avec un délai exponentiel à partir d'une seconde. Chaque tentative est journalisée avec son code de statut et son erreur. Après avoir corrigé le récepteur, rejouez une livraison enregistrée depuis le journal ; elle repart comme une nouvelle livraison. Changer l'adresse ou faire tourner le secret garde les livraisons signées, et supprimer un webhook supprime aussi son historique.
Catalogue des événements
Abonnez un récepteur aux événements utiles ; le nom de l'événement est le premier champ de chaque livraison.
Événements
- dpp.created - un passeport a été créé.
- dpp.updated - une nouvelle version immuable du passeport a été écrite.
- dpp.published - un passeport a été publié dans la vue publique.
- dpp.event_recorded - un événement de cycle de vie (réparé, transféré, recyclé, inspecté…).
- epcis.event - l'événement objet GS1 EPCIS 2.0 d'un événement de cycle de vie.
- compliance.alert - une validation a produit des constats de non-conformité.
- supplier.responded - un fournisseur a répondu à une demande via le portail.
- document.expiring - un document du coffre approche de sa date d'expiration.
- recall.issued - un passeport a été rappelé ; ses attestations sont révoquées et la page publique indique le rappel.
- dpp.reinstated - un passeport rappelé ou archivé a été rouvert pour correction.
- dpp.archived - un passeport a été retiré ; sa dernière version publiée reste lisible.
- channel.retraction_required - un passeport rappelé doit être retiré de chaque canal où il a été diffusé.
- channel.feed_ready - un flux marketplace ou boutique a été construit et envoyé.
- dpp.remanufactured - un passeport dérivé a été émis pour un article reconditionné ou remanufacturé.
- dpp.split et dpp.merged - un passeport a été scindé en articles sérialisés, ou plusieurs ont été regroupés.
- dpp.credential_issued - une attestation vérifiable a été signée pour un passeport publié.
- regulation.pack_changed - un référentiel a été capturé avec une nouvelle version, un nouveau statut ou de nouvelles règles.
- audit.chain_head - l'ancrage quotidien de la chaîne de hachage d'audit de l'organisation ; conservez-le pour vérifier la piste plus tard.
Abonnements EPCIS
Un abonnement EPCIS dans Settings, EPCIS est un webhook doté d'un filtre permanent sur les types d'événements, étapes métier, dispositions, produits, catégories ou passeports. Ses livraisons utilisent l'événement epcis.event, la même enveloppe et la même signature.