← Blog
10 min de lecture
|
Publié le
|
Mis à jour le

Signature des webhooks avec un secret personnel

Définissez un secret personnel et Chaingateway signe chaque webhook avec un en-tête X-Signature. Fonctionnement du HMAC, vérification en Node.js et limites.

Chapitres
C
Chaingateway Team
Experts blockchain

Relu par Maurice Sobiera

Un secret personnel est une clé que vous définissez dans votre profil Chaingateway. Une fois créé, chaque webhook sortant porte un en-tête X-Signature : un HMAC-SHA256 de l’identifiant de transaction, signé avec ce secret et encodé en Base64. Votre serveur recalcule la valeur et la compare, ce qui prouve que la requête vient de Chaingateway.

Pourquoi les webhooks ont-ils besoin d’une signature ?

L’endpoint d’un webhook est une URL publique, et toute personne qui la connaît peut lui envoyer une requête. Sans contrôle, une fausse requête « paiement reçu  » pourrait déclencher une livraison ou créditer un compte. Un secret partagé règle ce problème. Seuls Chaingateway et votre serveur connaissent la clé, et seuls eux peuvent donc produire une signature qui correspond. La construction s’appelle HMAC et est définie dans la RFC 2104 : une fonction de hachage combinée à une clé secrète.

Comment définir un secret personnel ?

Ouvrez les paramètres de votre profil dans le tableau de bord, repérez la carte du secret personnel de webhook et cliquez sur « Set Personal Secret  ». Pour remplacer un secret existant, cliquez sur « Regenerate Secret  ». Deux points de la documentation comptent :

  • Définir un secret pour la première fois active l’en-tête X-Signature sur tous les webhooks sortants. Assurez-vous que votre serveur accepte le nouvel en-tête et le vérifie avant de vous y fier.
  • Un secret régénéré prend effet immédiatement. Mettez votre gestionnaire à jour avant de cliquer, ou en même temps, sinon des notifications valides échouent à la vérification.

Comment la signature est-elle construite ?

La procédure documentée comporte trois étapes. Lisez le champ txid dans la charge utile du webhook. Calculez un HMAC-SHA256 avec votre secret personnel comme clé et la chaîne txid comme message. Encodez le résultat en Base64 et comparez-le avec l’en-tête. Voici à quoi ressemble une charge utile (tirée du guide des webhooks) :

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

Comment vérifier la signature sur votre serveur ?

Recalculez le HMAC à partir du txid et comparez-le à l’en-tête en temps constant. Le gestionnaire Express ci-dessous le fait. Il lit le secret dans une variable d’environnement, rejette un en-tête absent ou de mauvaise taille, et ne répond 200 que pour les requêtes valides :

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.json());
function isValid(txid, received, secret) {
const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
// timingSafeEqual throws when lengths differ, so check first
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/deposit', (req, res) => {
const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET);
if (!ok) return res.sendStatus(401);
// process req.body.txid, deduplicate on it, then acknowledge
res.sendStatus(200);
});
app.listen(3000);

La documentation propose aussi des versions en Python, Java et PHP. En Python, utilisez hmac.compare_digest pour la comparaison. En Node.js, crypto.timingSafeEqual joue le même rôle. Une comparaison simple avec == peut laisser fuiter des informations de timing.

Comment tester le gestionnaire ?

Calculez vous-même une signature et envoyez une fausse notification à votre serveur local. La commande openssl ci-dessous produit le même HMAC en Base64 que celui attendu par le gestionnaire. Utilisez un secret de test, jamais votre vrai secret :

Terminal window
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "{\"txid\": \"$TXID\"}"

Démarrez le serveur avec CG_PERSONAL_SECRET=test-secret. La requête renvoie 200. Modifiez un seul caractère du secret ou de la signature, et elle renvoie 401. Refaites ce test après chaque déploiement du gestionnaire, puis encore après avoir régénéré votre vrai secret.

Que ne couvre pas la signature ?

Elle couvre l’identifiant de transaction et rien d’autre. Selon la construction documentée, seul txid entre dans le HMAC. Deux conséquences en découlent :

  • Une signature valide prouve que Chaingateway a envoyé une notification pour cette transaction. Elle ne prouve pas que amount, to ou contractaddress dans le corps sont inchangés. Si ces champs décident d’un paiement, vérifiez-les sur la chaîne ou par rapport aux valeurs attendues pour la commande.
  • La même transaction peut arriver plusieurs fois, par exemple quand vous demandez le renvoi d’une notification échouée, et chaque copie porte la même signature valide. Dédupliquez sur txid.

Les webhooks ne sont pas renvoyés automatiquement. Les notifications échouées sont listées par chaîne, et vous demandez un nouvel envoi pour chacune. Solana n’a pas de webhooks. Là où des webhooks existent, la signature fonctionne de la même façon sur chaque chaîne.

Comment renouveler le secret sans perdre de notifications ?

Un secret régénéré prend effet immédiatement, et l’ordre des étapes compte donc. Faites accepter deux secrets au gestionnaire pendant une courte période, puis régénérez :

  1. Déployez une version du gestionnaire qui essaie d’abord le secret actuel, puis un second CG_PERSONAL_SECRET_NEXT facultatif si le premier contrôle échoue.
  2. Régénérez le secret dans votre profil et copiez la nouvelle valeur.
  3. Placez la nouvelle valeur dans CG_PERSONAL_SECRET_NEXT et redéployez.
  4. Envoyez un transfert de test sur le testnet et vérifiez que le gestionnaire l’accepte.
  5. Au bout d’un jour, promouvez le nouveau secret en CG_PERSONAL_SECRET et supprimez l’ancien.

La documentation n’indique pas quel secret signe une notification que vous renvoyez après une rotation. Gardez la fenêtre à deux secrets ouverte jusqu’à ce que la liste des notifications échouées soit vide.

Que se passe-t-il si vous n’avez pas défini de secret ?

Les webhooks sont alors envoyés sans l’en-tête X-Signature. Votre gestionnaire ne doit pas considérer un en-tête absent comme valide. Décidez selon l’environnement : en production, rejetez les requêtes sans signature dès que vous avez défini un secret, et dans un environnement de test local, vous pouvez les accepter. L’en-tête permet aussi de savoir si un secret est actif : une notification sans lui signifie qu’aucun secret n’est défini sur votre compte.

Où trouver la référence complète ?

Le guide de sécurité des webhooks présente les étapes et le code dans quatre langages, et le guide des webhooks explique comment créer des webhooks et des récepteurs.

Comment nous rédigeons ces articles

Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.

C
Chaingateway Team
Experts blockchain

L'équipe Chaingateway s'attache à simplifier l'intégration blockchain pour les développeurs du monde entier.