Aller au contenu

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.

Vérification de la signature : Chaingateway calcule le HMAC-SHA256 du txid avec votre secret personnel et l'envoie dans X-Signature, votre récepteur recalcule la valeur et la compare en temps constant Chaingateway signe base64( HMAC-SHA256( personal_secret, txid ) ) POST vers votre récepteur Corps JSON avec txid, en-tête X-Signature Le récepteur recalcule le HMAC même secret, même txid Comparaison en temps constant identiques : accepter, différentes : rejeteravec un statut d'erreur
Seul le txid est signé. Les autres champs du payload ne font pas partie de la signature.

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.

Vous définissez ou régénérez le secret personnel dans les paramètres de votre profil. Suivez ces étapes :

  1. Ouvrez les paramètres du profil.
  2. Repérez la section intitulée « Personal Secret ».
  3. 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.

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 hmac
import hashlib
import 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 usage
txid = '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.")

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_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-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.

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-Signature est absent ou incorrect, et journalisez-les.
  • Utilisez le txid comme clé d’idempotence. Une notification que vous renvoyez avec POST /api/v2/{chain}/webhooks/notifications/{id}/retry porte le même txid et 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.