Skip to main content
Chaque webhook est signé. Vérifiez systématiquement la signature avant de traiter une requête : c’est ce qui garantit que la livraison vient bien de Le Commis et n’a pas été altérée. Une requête dont la signature est invalide doit être rejetée et ignorée.

En-têtes reçus

Le Commis ajoute ces en-têtes à chaque POST :

Comment la signature est calculée

La signature est un HMAC-SHA256, encodé en hexadécimal et préfixé sha256=. La charge signée combine le timestamp et le corps brut de la requête :
Utilisez le corps brut (raw body) tel qu’il a été reçu, pas une version re-sérialisée après parsing JSON. Le moindre changement d’espaces ou d’ordre des clés casserait la comparaison. Lisez le corps brut avant que votre framework ne le parse.

Vérification pas à pas

1

Récupérez le corps brut et les en-têtes

Lisez le corps de la requête en chaîne brute, plus X-LeCommis-Signature et X-LeCommis-Timestamp.
2

Reconstituez la charge signée

Concaténez "{timestamp}.{corps brut}".
3

Calculez le HMAC attendu

HMAC_SHA256(signing_secret, charge_signée) encodé en hexadécimal, préfixé sha256=.
4

Comparez à temps constant

Comparez votre valeur à X-LeCommis-Signature avec une comparaison à temps constant (crypto.timingSafeEqual). N’utilisez jamais ==.
5

Rejetez les requêtes trop anciennes

Si |now - timestamp| > 5 min, rejetez la requête : c’est probablement un rejeu.

Exemple de vérification

Node.js (Express)
Si la signature est invalide ou le timestamp trop ancien, répondez 401 et ignorez la requête. Ne faites aucun traitement, ne re-fetch rien : une requête non signée ou périmée ne doit jamais déclencher d’action.

Le secret de signature

Le signing_secret est propre à chaque endpoint webhook, configuré depuis Réglages de l’établissement → Paramètres de l’API. Vous pouvez le régénérer (regenerate_secret) à tout moment depuis ces mêmes réglages — pensez alors à mettre à jour la valeur côté votre serveur. Stockez-le comme un secret (variable d’environnement, coffre-fort), jamais en clair dans le code.
Régénérer le secret depuis les Paramètres de l’API invalide immédiatement l’ancienne valeur : les livraisons signées avec l’ancien secret échoueront jusqu’à ce que votre serveur utilise le nouveau. Régénérez quand vous suspectez une fuite, puis déployez la nouvelle valeur sans délai.