Skip to main content
Chaque Pulse envoyé par Chariow est signé avec un secret propre à ce Pulse. Vérifier cette signature est le seul moyen de savoir qu’une requête reçue sur votre point de terminaison provient réellement de Chariow : votre URL est publique, donc quiconque la découvre peut y poster. Cette page constitue le contrat de signature complet. Implémentez-le une fois et vous pouvez faire confiance à chaque charge utile reçue.

En-têtes de la requête

Chaque livraison porte ces en-têtes :
Les événements de test envoyés depuis le tableau de bord portent x-pulse-id et x-pulse-event mais pas x-pulse-delivery-id, car aucun enregistrement de livraison n’est créé pour eux. Leur charge utile contient également un champ note supplémentaire. Les événements réels portent toujours les quatre en-têtes.

Le secret de signature

Chaque Pulse possède son propre secret de signature, préfixé whsec_, généré par Chariow à la création du Pulse.
Le secret de signature n’est pas votre clé API, et il n’est dérivé ni de votre clé API, ni de l’identifiant de votre boutique, ni d’aucun autre identifiant d’intégration. C’est une valeur indépendante. Calculer le HMAC avec autre chose ne produira jamais une signature correspondante.
Pour le récupérer : Automatisations → Pulses → sélectionnez votre Pulse → onglet Aperçu → Secret de signature. Il est masqué par défaut ; utilisez Révéler, Copier et Renouveler sur ce bloc. Le secret est chiffré au repos et n’apparaît jamais dans les listings d’API ni dans les journaux de requêtes — ceux-ci n’exposent qu’une forme masquée du type whsec_••••a1b2. La valeur en clair n’est renvoyée que sur une demande de révélation explicite.

Renouveler le secret

Le renouvellement prend effet immédiatement et est irréversible : l’ancien secret cesse de fonctionner à l’instant du renouvellement. Mettez à jour la configuration de votre point de terminaison dans la même fenêtre. Les livraisons émises avant le renouvellement conservent la signature calculée avec l’ancien secret : adoptez le nouveau secret avant de rejouer d’anciennes livraisons.

Schéma de signature

Seul le corps brut est signé. La méthode HTTP, l’URL, les en-têtes, x-pulse-id, x-pulse-delivery-id et tout horodatage sont exclus du calcul.

Encodage du corps

Le corps est du JSON compact en UTF-8 :
  • aucun espace d’indentation ni retour à la ligne ;
  • les barres obliques sont échappées — https:\/\/example.com ;
  • les caractères non-ASCII sont échappés en \uXXXX, le corps transmis est donc en pratique de l’ASCII ;
  • l’ordre des clés est celui du corps transmis.
Ne re-sérialisez jamais la charge utile parsée. JSON.stringify(req.body) ou json.dumps(payload) ne reproduiront pas ces octets — les barres obliques échappées suffisent à casser l’empreinte. Capturez le corps brut avant tout parsing JSON.

Comparer la signature

Retirez le préfixe sha256= et comparez à l’empreinte hexadécimale seule, ou reconstruisez "sha256=" + empreinte et comparez la chaîne complète. Les deux fonctionnent, à condition d’être cohérent. Comparez toujours en temps constant (crypto.timingSafeEqual, hash_equals, hmac.compare_digest) et vérifiez d’abord que les deux valeurs ont la même longueur — timingSafeEqual lève une exception sur des tampons de tailles différentes. Le préfixe identifie l’algorithme afin que le schéma puisse évoluer sans casser les intégrations existantes. Traitez toute valeur qui ne commence pas par sha256= comme un schéma que vous ne prenez pas encore en charge.
Rejetez avec un 401 toute requête dépourvue d’un en-tête x-chariow-signature valide.

Exemples de vérification

Idempotence et protection contre le rejeu

La signature ne contient aucun horodatage, et c’est délibéré. Elle est calculée une seule fois à l’émission de la livraison et réutilisée à l’identique par chaque réessai. Une fenêtre temporelle rejetterait à tort un réessai légitimement retardé — la dernière tentative d’une livraison peut arriver près de trois heures après la première. La protection contre le rejeu repose sur x-pulse-delivery-id. Cet identifiant est stable sur toutes les tentatives d’une même livraison, ce qui en fait une clé d’idempotence directement exploitable :
  1. Lisez x-pulse-delivery-id.
  2. Si vous l’avez déjà traité, renvoyez 200 et arrêtez-vous.
  3. Sinon, persistez-le, renvoyez 200, puis traitez de façon asynchrone.
Dédupliquez sur x-pulse-delivery-id, pas sur l’identifiant de l’entité contenue dans la charge utile. Une même vente peut légitimement produire plusieurs livraisons — une par Pulse abonné, plus tout rejeu manuel que vous déclenchez vous-même.
Une livraison rejouée manuellement est une nouvelle livraison, avec son propre x-pulse-delivery-id : elle passera donc votre contrôle d’idempotence et sera traitée à nouveau. C’est le comportement voulu — le rejeu existe précisément pour retraiter un événement que votre point de terminaison a manqué.

Diagnostiquer une signature qui ne correspond pas

Utilisez l’onglet Livraisons de la page du Pulse pour rejouer une livraison réelle pendant votre mise au point. Il affiche la charge utile exacte envoyée et la réponse exacte de votre point de terminaison, bien plus utile qu’un événement de test pour valider la vérification de bout en bout.

Ressources associées

Guide des Pulses

Événements, charges utiles, historique de livraison et réessais

Meilleures pratiques

Recommandations de sécurité et de fiabilité