Vérifier les signatures de webhook avec HMAC
L’en-tête X-Signature d’un webhook Chaingateway permet de vérifier qu’une requête provient bien de Chaingateway. Il contient le HMAC-SHA256, encodé en base64, de l’identifiant de transaction (txid) du payload, avec votre secret personnel comme clé. Votre récepteur recalcule la valeur et la compare à l’en-tête. L’en-tête est envoyé dès que vous avez défini un secret personnel.
Contre quoi l’en-tête X-Signature protège-t-il ?
Section intitulée « Contre quoi l’en-tête X-Signature protège-t-il ? »Il protège contre les requêtes falsifiées : n’importe qui peut envoyer une requête POST à l’URL publique de votre récepteur, mais seul un émetteur qui connaît le secret personnel peut produire une signature correspondante. HMAC, défini dans la RFC 2104, combine une fonction de hachage avec une clé secrète, ici SHA-256. NIST FIPS 198-1 spécifie la même construction sous le nom de Keyed-Hash Message Authentication Code.
La signature couvre le txid et rien d’autre. Le montant, les adresses et les champs de token du corps ne sont pas signés. Une paire valide de txid et de signature ne prouve donc pas que le reste du corps est inchangé. Après la vérification, traitez le txid comme une clé de recherche : lisez la transaction avec GET /api/v2/{chain}/transactions/{txid} et créditez le paiement à partir des données renvoyées par l’API, pas à partir du montant figurant dans le corps de la notification.
Comment définir le secret personnel ?
Section intitulée « Comment définir le secret personnel ? »Vous définissez ou régénérez le secret personnel dans les paramètres de votre profil. Suivez ces étapes :
- Ouvrez les paramètres du profil.
- Repérez la section intitulée « Personal Secret ».
- Si aucun secret n’est défini, cliquez sur « Set Personal Secret » pour en générer un. Si un secret existe, cliquez sur « Regenerate Secret » pour le remplacer.
Deux points comptent pour un système en production. Si vous n’avez pas encore de secret personnel, en ajouter un active l’en-tête X-Signature sur tous les webhooks sortants. Déployez un récepteur qui accepte et vérifie l’en-tête avant de le faire. Si vous régénérez un secret existant, le nouveau secret s’applique immédiatement aux notifications de webhook. Mettez le récepteur à jour en même temps, sinon il rejette des requêtes valides.
Comment l’en-tête X-Signature est-il construit ?
Section intitulée « Comment l’en-tête X-Signature est-il construit ? »Chaingateway lit le txid du payload, calcule dessus un HMAC avec la fonction de hachage SHA-256 en utilisant le secret personnel comme clé, puis encode en base64 les 32 octets obtenus. Le txid est l’identifiant unique de transaction qui figure déjà dans le corps du webhook : le récepteur a donc tout ce qu’il faut pour recalculer la valeur. Le secret n’est partagé qu’entre Chaingateway et vous.
Comment vérifier la signature dans mon code ?
Section intitulée « Comment vérifier la signature dans mon code ? »Recalculez le HMAC à partir du txid du corps et comparez-le à la valeur de l’en-tête. Utilisez une fonction de comparaison en temps constant, afin que la durée de la comparaison ne révèle rien sur la valeur attendue. Les exemples ci-dessous le font en Python, Java, PHP et JavaScript.
import hmacimport hashlibimport base64
def verify_signature(txid, received_signature, personal_secret): # Generate the expected signature expected_signature = base64.b64encode(hmac.new( personal_secret.encode(), txid.encode(), hashlib.sha256 ).digest()).decode()
# Compare the expected signature with the received signature return hmac.compare_digest(expected_signature, received_signature)
# Example usagetxid = 'your_txid_here'received_signature = 'received_signature_here'personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret): print("Signature is valid.")else: print("Invalid signature.")import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;
public class SignatureVerifier { public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKeySpec);
byte[] signatureBytes = mac.doFinal(txid.getBytes(StandardCharsets.UTF_8)); String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);
// Constant-time comparison return MessageDigest.isEqual( expectedSignature.getBytes(StandardCharsets.UTF_8), receivedSignature.getBytes(StandardCharsets.UTF_8)); }
public static void main(String[] args) { try { String txid = "your_txid_here"; String receivedSignature = "received_signature_here"; String personalSecret = "your_personal_secret_here";
if (verifySignature(txid, receivedSignature, personalSecret)) { System.out.println("Signature is valid."); } else { System.out.println("Invalid signature."); } } catch (Exception e) { e.printStackTrace(); } }}<?phpfunction verifySignature($txid, $receivedSignature, $personalSecret) { // Generate the expected signature $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));
// Compare the expected signature with the received signature return hash_equals($expectedSignature, $receivedSignature);}
// Example usage$txid = 'your_txid_here';$receivedSignature = 'received_signature_here';$personalSecret = 'your_personal_secret_here';
if (verifySignature($txid, $receivedSignature, $personalSecret)) { echo "Signature is valid.";} else { echo "Invalid signature.";}const crypto = require('crypto');
function verifySignature(txid, receivedSignature, personalSecret) { // Generate the expected signature const expectedSignature = crypto .createHmac('sha256', personalSecret) .update(txid) .digest('base64');
// timingSafeEqual throws if the lengths differ, so check them first const expected = Buffer.from(expectedSignature); const received = Buffer.from(receivedSignature); return expected.length === received.length && crypto.timingSafeEqual(expected, received);}
// Example usageconst txid = 'your_txid_here';const receivedSignature = 'received_signature_here';const personalSecret = 'your_personal_secret_here';
if (verifySignature(txid, receivedSignature, personalSecret)) { console.log("Signature is valid.");} else { console.log("Invalid signature.");}Comment tester mon code de vérification ?
Section intitulée « Comment tester mon code de vérification ? »Testez la fonction avec une entrée fixe avant de la connecter au trafic réel. Les valeurs ci-dessous forment un vecteur de test que vous pouvez reproduire avec n’importe quel outil HMAC-SHA256. Le secret est un espace réservé, pas un vrai secret personnel. Si votre fonction renvoie une valeur différente pour cette entrée, le bug se trouve dans votre code et non dans le webhook.
personal_secret: my_personal_secrettxid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=Les erreurs courantes consistent à hacher tout le corps JSON au lieu du txid, à utiliser le condensé hexadécimal au lieu de base64, et à comparer avec ==, qui n’est pas en temps constant. N’oubliez pas non plus que le secret personnel s’applique à tout le compte. Un secret que vous régénérez dans les paramètres du profil modifie d’un coup la signature de tous les webhooks du compte.
Que faire quand la signature ne correspond pas ?
Section intitulée « Que faire quand la signature ne correspond pas ? »Rejetez la requête avec un statut d’erreur tel que 401 ou 403 et ne traitez pas le corps. Journalisez le txid, l’en-tête reçu et l’adresse source, afin de distinguer un secret mal configuré d’une requête falsifiée. Si le même émetteur produit des écarts juste après la régénération du secret, le récepteur utilise encore l’ancien. Une requête falsifiée qui se contente de deviner un txid ne peut pas produire de signature valide sans le secret.
Que doit faire d’autre un récepteur de webhook ?
Section intitulée « Que doit faire d’autre un récepteur de webhook ? »La vérification de la signature est une couche parmi d’autres. Les mesures suivantes couvrent le reste du parcours.
- Servez le récepteur en HTTPS, afin que le payload soit chiffré en transit. La REST Security Cheat Sheet d’OWASP recommande HTTPS pour tout endpoint qui traite des données sensibles.
- Rejetez avec un statut d’erreur les requêtes dont l’en-tête
X-Signatureest absent ou incorrect, et journalisez-les. - Utilisez le
txidcomme clé d’idempotence. Une notification que vous renvoyez avecPOST /api/v2/{chain}/webhooks/notifications/{id}/retryporte le mêmetxidet ne doit pas créditer un paiement deux fois. - Conservez le secret personnel dans un coffre de secrets, jamais dans le dépôt, et renouvelez-le s’il a pu fuiter. Chaingateway ne rejoue pas les livraisons échouées de lui-même : prévoyez la mise à jour du récepteur et du secret comme une seule étape, puis renvoyez ensuite les notifications manquées depuis la liste des échecs.
- RFC 2104, HMAC: Keyed-Hashing for Message Authentication
- NIST FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)
- OWASP REST Security Cheat Sheet
- Webhooks dans cette documentation pour le payload et les endpoints de renvoi.