Node Crypto n8n : hash, HMAC et vérification de signatures webhook

Un webhook n8n exposé sur Internet accepte par défaut n'importe quelle requête POST : rien ne distingue un événement légitime envoyé par Stripe d'une requête forgée par un tiers qui a trouvé l'URL. C'est pour cela que Stripe, GitHub ou Shopify signent chaque webhook avec un HMAC : le destinataire recalcule la signature avec le secret partagé et rejette tout ce qui ne correspond pas. Dans n8n, le node Crypto couvre ce besoin sans écrire de code — et rend au passage d'autres services : clés d'idempotence, détection de changements, pseudonymisation, tokens à usage unique. Ce guide fait le tour de ses opérations, montre la vérification de signature de bout en bout, et indique quand basculer sur un node Code.

Les opérations du node Crypto

Le node Crypto (un core node, sans credential pour la plupart des opérations) propose six actions :

• Hash : calcule l'empreinte d'un texte ou d'un fichier binaire. Algorithmes disponibles : MD5, SHA256, SHA3-256, SHA3-384, SHA3-512, SHA384, SHA512, sortie encodée en HEX ou BASE64. Pour un fichier, on active l'option binaire et on indique le nom de la propriété (par exemple data).
• Hmac : mêmes algorithmes et encodages que Hash, mais l'empreinte est calculée avec un secret — l'opération qui sert à vérifier les signatures de webhooks et à produire des hashes non précalculables.
• Sign : signe une valeur avec une clé privée (RSA, ECDSA…) et l'algorithme choisi dans la liste proposée par le node, sortie en HEX ou BASE64. Utile quand c'est vous qui devez prouver l'origine d'un message auprès d'une API partenaire.
• Generate : génère une chaîne aléatoire au format ASCII, BASE64, HEX ou UUID, avec une longueur configurable (32 par défaut, hors UUID).
• Encrypt / Decrypt : chiffrement symétrique par phrase de passe, ou asymétrique RSA — ce dernier limité à de petits contenus (environ 190 octets avec une clé 2048 bits), donc réservé à des secrets courts.

Le résultat est écrit dans une propriété de l'item, exploitable par les nodes suivants via une expression {{ $json.data }}.

Vérifier la signature HMAC d'un webhook entrant

Le principe est le même chez tous les fournisseurs : le corps brut de la requête est haché en HMAC-SHA256 avec un secret que vous seul connaissez, et le résultat voyage dans un en-tête HTTP :

• GitHub : en-tête X-Hub-Signature-256, HMAC-SHA256 en hexadécimal préfixé par sha256=.
• Shopify : en-tête X-Shopify-Hmac-Sha256, HMAC-SHA256 encodé en base64.
• Stripe : en-tête Stripe-Signature au format t=timestamp,v1=signature, le HMAC portant sur la concaténation timestamp.corps.

La vérification côté n8n, pour un cas simple comme GitHub ou Shopify :

1. Node Webhook avec l'option Raw Body activée : la signature porte sur les octets exacts du corps, pas sur un JSON re-sérialisé par n8n. C'est le point qui fait échouer la plupart des premières tentatives — voir notre guide complet du node Webhook.
2. Node Crypto, opération Hmac, type SHA256, avec le corps brut en entrée (mode binaire si besoin), votre secret de webhook, et l'encodage attendu : HEX pour GitHub, BASE64 pour Shopify.
3. Node IF qui compare la signature calculée à l'en-tête reçu, par exemple {{ $json.data === $('Webhook').item.json.headers['x-shopify-hmac-sha256'] }} (n8n met les noms d'en-têtes en minuscules).
4. Branche fausse : un Respond to Webhook renvoie un code 401 ; branche vraie : le traitement continue.

Cette étape s'ajoute aux autres protections (authentification du node, allowlist d'IP) décrites dans notre article sur la sécurisation des webhooks n8n. Le mécanisme HMAC lui-même n'a rien d'artisanal : la construction a été formalisée et prouvée sûre par Mihir Bellare, Ran Canetti et Hugo Krawczyk dans « Keying Hash Functions for Message Authentication », publié à CRYPTO 1996 — l'article qui a introduit HMAC, standardisé ensuite dans la RFC 2104.

Pour Stripe, la concaténation timestamp.corps et le découpage de l'en-tête Stripe-Signature se font plus confortablement dans un node Code, comme ci-dessous. Notre article sur les webhooks Stripe et les relances de paiement montre le pipeline complet côté métier.

Quand le node ne suffit pas : node Code et comparaison à temps constant

Comparer deux signatures avec === dans un node IF fonctionne, mais la comparaison s'interrompt au premier caractère différent : le temps de réponse varie selon le nombre de caractères corrects, ce qui fuit théoriquement de l'information. David Brumley et Dan Boneh ont montré dans « Remote Timing Attacks are Practical » (12e USENIX Security Symposium, 2003) que ces attaques par mesure de temps, longtemps jugées cantonnées aux cartes à puce, s'exploitent à travers un réseau contre de vrais serveurs. Sur un workflow n8n dont la latence est dominée par le réseau, l'exploitation est très difficile en pratique — mais la version à temps constant ne coûte que quelques lignes :

const crypto = require('crypto');

const secret = $env.WEBHOOK_SECRET;
const rawBody = $json.rawBody; // corps brut, préservé tel quel
const received = $json.headers['x-hub-signature-256'] ?? '';

const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

const a = Buffer.from(expected);
const b = Buffer.from(received);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);

return [{ json: { valid } }];

Deux prérequis : le module natif crypto doit être autorisé dans le node Code via la variable d'environnement NODE_FUNCTION_ALLOW_BUILTIN (marche à suivre dans notre guide sur les modules npm dans le node Code), et le secret doit venir d'une variable d'environnement plutôt que d'être collé en dur — voir nos bonnes pratiques pour sécuriser les credentials et clés API. Le node Code reprend aussi la main pour les encodages que le node Crypto ne propose pas (base64url, sortie binaire brute) ; la syntaxe générale est couverte dans notre guide des expressions et du JavaScript dans le node Code.

Quatre autres patterns utiles en automatisation

Clé d'idempotence par hash du payload

Un fournisseur qui relivre deux fois le même webhook, un formulaire soumis en double : hasher en SHA256 les champs significatifs du payload donne une clé stable, à vérifier dans une table (Data Table, Redis, Postgres) avant de traiter. Si la clé existe déjà, l'item s'arrête là — le pattern complet est dans notre article sur l'idempotence des webhooks.

Détecter les changements avant un traitement coûteux

Avant de recalculer des embeddings ou de relancer un appel LLM sur un document, comparez le SHA256 du contenu actuel à celui stocké au dernier passage : si l'empreinte n'a pas bougé, inutile de payer le traitement. Sur une base documentaire re-synchronisée chaque nuit, ce test évite de re-vectoriser l'écrasante majorité de fichiers inchangés.

Pseudonymiser des données personnelles dans les logs

Journaliser l'activité d'un workflow sans stocker d'emails en clair : l'opération Hmac (et non Hash) avec un secret dédié produit un identifiant stable — le même email donne toujours le même pseudonyme — mais non réversible sans le secret, là où un simple SHA256 d'email se casse par dictionnaire. Cela reste une pseudonymisation au sens du RGPD, pas une anonymisation. Le sujet est approfondi dans nos articles sur le traitement des demandes RGPD avec n8n et la piste d'audit RGPD avec n8n et Supabase ; pour des workflows prêts à l'emploi, le Pack Conformité & Audit (149 €) assemble l'ensemble.

Générer des tokens à usage unique

L'opération Generate en format HEX (32 caractères ou plus) produit un token imprévisible pour un lien de confirmation, de désinscription ou de téléchargement à durée limitée ; le format UUID convient pour des identifiants de corrélation. Stockez le token avec une date d'expiration, puis invalidez-le après usage.

Bonnes pratiques et limites

• MD5 n'est plus un algorithme de sécurité : des collisions se construisent volontairement. Acceptable comme empreinte de déduplication interne, jamais pour une signature face à un adversaire.
• Le corps brut est non négociable pour les signatures : tout re-parsing JSON avant le calcul HMAC change les octets et invalide la comparaison.
• Un secret par intégration, stocké en variable d'environnement ou credential chiffré — jamais en dur dans un node.
• Le node Crypto ne remplace pas une gestion de clés : la clé privée de l'opération Sign se traite comme n'importe quel credential sensible, avec rotation planifiée.

En résumé

Le node Crypto couvre les besoins cryptographiques courants d'un workflow n8n : Hash et Hmac (MD5 à SHA3-512, sortie HEX ou BASE64), Sign avec clé privée, Generate pour l'aléatoire, Encrypt/Decrypt pour de petits secrets. La vérification de signature webhook tient en trois nodes — Webhook en Raw Body, Crypto en Hmac, IF pour la comparaison — et bascule sur un node Code avec timingSafeEqual pour une comparaison à temps constant ou un encodage que le node n'expose pas. Ajoutez les hashes d'idempotence, la détection de changements et la pseudonymisation des logs, et ce petit node sans credential devient l'un des plus rentables de la palette n8n.