En-têtes de chaque envoi
Comment la signature est calculée
Pulse-Sell calcule un HMAC-SHA256 du texte<t>.<corps brut> avec le secret de votre Pulse (celui qui commence par pulse_whsec_). Le résultat, en hexadécimal, est placé dans v1, et l’horodatage t est dans le texte signé : un attaquant ne peut pas le changer.
1
Lisez le corps brut
Prenez les octets reçus avant tout parsing JSON. Ré-encoder un objet change les espaces et l’ordre, et la signature ne correspondra plus.
2
Extrayez t et v1
Découpez l’en-tête sur la virgule, puis sur le signe égal.
3
Refusez les envois anciens
Si
t s’écarte de plus de 5 minutes de l’heure de votre serveur, refusez : c’est un rejeu.4
Recalculez et comparez
Calculez le HMAC de
t + "." + corps, puis comparez en temps constant.5
Répondez 2xx, puis traitez
Ne parsez le JSON qu’après vérification. Répondez vite, et faites le travail long en arrière-plan.
Bonnes pratiques de sécurité
- Un secret par Pulse. Il est distinct de votre clé d’API : le compromettre ne donne aucun accès à l’API.
- Stockez le secret dans une variable d’environnement, jamais dans le code.
- Utilisez toujours le corps brut pour la vérification.
- Comparez en temps constant (
timingSafeEqual,compare_digest,hash_equals), jamais avec==. - Dédoublonnez : un même événement peut être livré plus d’une fois (relance, réponse perdue). Gardez l’identifiant
event.id(ouX-PulseSell-Event-Id) déjà traité. - Ne vous fiez pas à l’adresse IP de l’émetteur : fiez-vous à la signature.
- Servez votre endpoint en HTTPS uniquement.
- Ne journalisez pas les e-mails de vos clients en clair.
Changer le secret
Si le secret a fuité, régénérez-le :POST /pulses/{id}/rotate-secret (permission pulses.write) ou dans le tableau de bord. L’ancien secret cesse de signer immédiatement ; le nouveau est affiché une seule fois. Mettez à jour votre serveur aussitôt : les envois signés avec le nouveau secret échoueront à la vérification tant que vous ne l’avez pas fait, puis seront relancés.

