Validateur de signature des webhooks Streams

Un serveur Express léger qui vérifie les signatures HMAC-SHA256 des webhooks Quicknode Streams et prend en charge les corps de requêtes compressés au format gzip.

Consulter le dépôt

Framework/bibliothèque front-end :

Express

Langue :

JavaScript

Outil de compilation/serveur de développement :

Node.js

Aperçu

Quicknode Streams peut signer chaque transmission de webhook à l'aide d'une signature HMAC-SHA256, ce qui vous permet de vérifier qu'une requête provient bien de Quicknode et qu'elle n'a pas été altérée pendant le transfert. Cet exemple d'application est un serveur Express minimaliste qui montre précisément comment vérifier ces signatures, y compris dans le cas particulier où Streams envoie un corps de requête compressé au format gzip.

La signature est calculée sur la concaténation de nonce + horodatage + charge utile (UTF-8), en fonction de votre flux jeton de sécurité. Lorsque la compression est activée, Streams signe le JSON non compressé avant de le compresser au format gzip pour le transfert ; le vérificateur doit donc appliquer l'algorithme HMAC aux octets décodés plutôt qu'aux octets gzip bruts. Cette application utilise express.raw() grâce à la décompression gzip intégrée à body-parser, qui permet de gérer cela correctement.

Pour une explication détaillée du fonctionnement de la vérification des signatures, consultez le guide associé : « Comment valider les messages Webhook provenant de flux entrants ».

Pile technologique

Environnement d'exécution: Node.js (>=16)
Framework: Express
Langage: JavaScript
Crypto: Fonctionnalités intégrées de Node.js crypto module (HMAC-SHA256)

Fonctionnalités

Vérification HMAC-SHA256: Vérifie la validité de la x-qn-signature en-tête par rapport à un condensé calculé localement à l'aide de votre jeton de sécurité Stream.
Prise en charge du corps de message au format Gzip: Gère correctement Content-Encoding : gzip les requêtes en effectuant un HMAC sur le JSON décompressé, et non sur les octets bruts.
Comparaison sans risque de synchronisation: Utilisations crypto.timingSafeEqual afin d'empêcher les attaques par timing lors de la comparaison des signatures.
Journalisation de débogage: affiche le nonce, l'horodatage, un aperçu de la charge utile, ainsi que les signatures calculées et fournies, afin de faciliter le débogage local.
Port configurable: La valeur par défaut est 9999; remplacer par le PORT variable d'environnement.

Prérequis

Node.js v16 ou une version ultérieure doit être installé sur votre ordinateur.
Un compte Quicknode sur lequel au moins un flux est configuré.
Le jeton de sécurité figurant dans l'onglet « Paramètres » de votre Stream, dans le tableau de bord Quicknode.
ngrok (ou tout autre outil de tunnel) pour rendre votre serveur local accessible depuis Internet afin que Streams puisse y accéder.

Structure du projet

streams-webhook-validate-signature/
├── .env.example    # Modèle de variables d'environnement
├── .gitignore
├── package.json
├── package-lock.json
└── server.js       # Récepteur de webhooks Express et vérificateur HMAC

Variables d'environnement

Copier .env.example to .env et configurez votre jeton de sécurité Stream :

QN_STREAM_SECRET=votre_jeton_de_sécurité_de_plus_de_32_octets_ici

Vous trouverez ce jeton dans l'onglet « Paramètres » de votre flux, à l'adresse dashboard.quicknode.com/streams.

Démarrer

1. Cloner le dépôt

git clone https://github.com/quiknode-labs/streams-webhook-validate-signature.git
cd streams-webhook-validate-signature

2. Installer les dépendances

npm installer

3. Configurer les variables d'environnement

cp .env.example .env

Ouvrir .env et définir QN_STREAM_SECRET à votre jeton de sécurité Stream.

4. Démarrer le serveur

npm démarrer

Le serveur écoute sur http://localhost:9999/webhook par défaut. Pour utiliser un autre port :

PORT=3000 npm start

5. Publier avec ngrok

Streams a besoin d'une URL accessible au public pour transmettre les webhooks. Dans un autre terminal :

ngrok http 9999

Copiez l'URL de redirection HTTPS (par exemple : https://abc123.ngrok.io) et définissez-la comme URL du webhook de votre Stream à l'aide de la /webhook chemin ajouté :

https://abc123.ngrok.io/webhook

6. Envoyer une charge utile de test

Une fois l'URL du webhook enregistrée, utilisez le bouton « Envoyer la charge utile » dans le tableau de bord Streams pour déclencher une transmission test signée sans attendre qu'une activité réelle ait lieu sur la blockchain. Cela fonctionne aussi bien lors de la création d'un nouveau Stream que lors de la modification d'un Stream existant. Vérifiez la sortie de débogage de la signature dans le terminal de votre serveur pour vous assurer que la requête a bien été reçue et vérifiée.

Points de terminaison de l'API

Méthode	Chemin d'accès	Description
`POST`	`/webhook`	Reçoit et vérifie la transmission d'un webhook Streams

En-têtes de requête attendus

En-tête	Description
`x-qn-nonce`	Nonce aléatoire inclus dans les données d'entrée de la signature
`x-qn-timestamp`	Horodatage Unix inclus dans les données d'entrée de la signature
`x-qn-signature`	Digest HMAC-SHA256 codé en hexadécimal à vérifier

Réponses

Statut	Signification
`200`	Signature vérifiée avec succès
`400`	Les en-têtes obligatoires sont manquants
`401`	Échec de la vérification de la signature
`500`	Mauvaise configuration du serveur (clé secrète manquante) ou erreur de traitement