Comprendre et sécuriser les webhooks

Un webhook est fondamentalement une porte ouverte dans votre système n8n : dès qu'un service externe envoie une requête HTTP à l'URL générée par le nœud Webhook, le workflow associé démarre automatiquement, sans planification et sans clic manuel. C'est précisément cette ouverture qui rend les webhooks si utiles pour les intégrations avec Stripe, GitHub, des outils de formulaires ou vos propres applications. Mais elle transforme aussi l'URL en point d'attaque si aucune authentification, aucun filtre IP et aucune vérification de signature ne s'interposent. Quiconque connaît ou devine l'URL peut déclencher le workflow.

Cet article présente la structure du nœud Webhook dans n8n, les méthodes d'authentification intégrées, le filtrage par liste blanche d'IP comme couche de protection supplémentaire, et la configuration derrière un reverse proxy, un point qui prête régulièrement à confusion sur les instances n8n auto-hébergées. Mise à jour : juillet 2026.

Comment le nœud Webhook est structuré

Selon la documentation n8n sur le nœud Webhook, le nœud prend en charge six méthodes HTTP : DELETE, GET, HEAD, PATCH, POST et PUT. Dans le champ Path, vous définissez le chemin de l'URL, soit librement, soit avec des espaces réservés comme `/:variable` pour des segments dynamiques. Sans saisie de votre part, n8n génère un chemin aléatoire, ce qui évite les collisions avec d'autres workflows.

Pour la réponse, plusieurs options sont disponibles :

• Immediately: Le webhook répond immédiatement avec le message indiquant que le workflow a démarré, sans attendre sa fin.
• When Last Node Finishes: La réponse contient les données du dernier nœud exécuté.
• Using Respond to Webhook Node: Un nœud dédié dans le workflow contrôle précisément le code de statut, les en-têtes et le corps de la réponse.
• Streaming response: Pour les nœuds prenant en charge le streaming, la réponse peut être transmise en temps réel.

Important en pratique : selon la documentation, n8n n'enregistre qu'une seule combinaison de chemin et de méthode HTTP à la fois. Deux workflows actifs avec le même chemin et la même méthode se bloquent mutuellement ; il faut désactiver l'un des deux, ou modifier le chemin ou la méthode.

Authentification directement dans le nœud Webhook

Avant de penser aux filtres IP ou aux règles de reverse proxy, vous devriez utiliser l'authentification intégrée du nœud Webhook. Selon la documentation sur les identifiants Webhook quatre options sont disponibles :

• Basic Auth: Le service appelant doit envoyer un nom d'utilisateur et un mot de passe dans l'en-tête Authorization. Simple à mettre en place, mais utile uniquement en combinaison avec HTTPS, car il n'apporte pas de chiffrement supplémentaire.
• Header Auth: Vous définissez un nom d'en-tête, par exemple `X-API-Key`, et une valeur secrète. n8n vérifie chaque requête entrante pour cet en-tête précis. Cette méthode convient bien aux services qui envoient déjà une clé API.
• JWT Auth: La requête doit contenir un JSON Web Token signé numériquement. n8n vérifie la signature via une phrase secrète ou une clé PEM que vous enregistrez dans l'identifiant.
• None: Aucune vérification, toute requête avec le chemin correct est acceptée. Ce réglage convient tout au plus pour de brefs tests, pas pour des workflows en production.

La documentation précise un point important : la méthode choisie doit correspondre à ce que le service appelant envoie réellement. Un webhook GitHub, par exemple, signe généralement les requêtes via une signature HMAC dans l'en-tête, que vous pouvez vérifier en plus de la Header Auth dans un nœud Code, si vous souhaitez sécuriser au-delà de la simple authentification du nœud.

Le filtrage par liste blanche d'IP comme couche de protection supplémentaire

En plus de l'authentification, le nœud Webhook propose l'option IP(s) Whitelist. Vous y saisissez une liste d'adresses IP autorisées séparées par des virgules ; selon la documentation, n8n répond par une erreur 403 aux requêtes provenant d'adresses non répertoriées. Si le champ reste vide, toutes les adresses sont autorisées.

En pratique, la liste blanche d'IP fonctionne mieux comme deuxième couche à côté de Header Auth ou JWT Auth, pas comme protection unique : si un service comme Stripe ou GitHub dispose de plages d'IP d'envoi fixes, vous les saisissez et bloquez ainsi tout le reste par défaut. Pour les services avec des plages d'IP changeantes ou incertaines, la vérification par en-tête ou JWT reste la méthode la plus fiable. Vous gardez ainsi le contrôle sur qui peut même atteindre le workflow avant que la logique proprement dite ne commence à s'exécuter.

Configurer correctement les webhooks derrière un reverse proxy

Si n8n est auto-hébergé derrière un reverse proxy, par exemple Caddy, Nginx ou Traefik, la détection automatique de l'URL ne fonctionne plus de manière fiable : n8n fonctionne généralement en interne sur le port 5678, tandis que le proxy expose l'application vers l'extérieur via le port 443. Selon la documentation n8n sur la configuration de l'URL de webhook derrière un reverse proxy vous résolvez cela avec deux variables d'environnement :

• WEBHOOK_URL: Définit l'adresse complète et publiquement accessible que n8n affiche dans l'éditeur et enregistre auprès des services externes, par exemple `https://n8n.exemple.fr/`.
• N8N_PROXY_HOPS: Doit être défini sur le nombre de proxys en amont, généralement 1. Cela permet à n8n d'interpréter correctement les en-têtes transmis par un proxy.

Le proxy lui-même doit transmettre les en-têtes `X-Forwarded-For`, `X-Forwarded-Host` et `X-Forwarded-Proto`. Si cette configuration manque, la liste blanche d'IP de la section précédente peut ne servir à rien, car n8n ne voit alors que l'adresse interne du proxy au lieu de l'adresse IP réelle de l'expéditeur. Selon la documentation n8n, ce lien précis est l'une des sources d'erreur les plus fréquentes : des IP en liste blanche sont rejetées bien que la liste soit correctement tenue à jour, parce que N8N_PROXY_HOPS est absent ou mal défini.

Ne pas confondre l'URL de test et l'URL de production

Chaque nœud Webhook génère deux URL différentes. L'URL de test affiche les données entrantes dans l'éditeur dès que vous cliquez sur Listen for Test Event dans le nœud, mais selon la documentation, elle ne reste active que 120 secondes. L'URL de production ne prend effet qu'une fois le workflow publié, mais n'affiche alors plus les données dans l'éditeur, uniquement dans l'onglet Executions.

Une erreur typique en pratique : un service externe est configuré pendant le développement sur l'URL de test, car elle fournit un retour visible dans l'éditeur. Après la publication du workflow, le webhook ne fonctionne alors plus, car le service continue d'utiliser l'ancienne URL de test au lieu de l'URL de production. Vérifiez donc, avant chaque mise en production, que l'URL de production est bien enregistrée dans le système appelant. Ceux qui utilisent n8n comme collaboratrice numérique auto-hébergée et qui accordent de l'importance à une sécurisation des webhooks propre et traçable trouveront auprès du conseil n8n de NordFlux un accompagnement pour la mise en place, l'authentification et la configuration du reverse proxy.

Questions fréquentes

Header Auth seule suffit-elle pour sécuriser un webhook ?

Pour de nombreuses automatisations internes, Header Auth via HTTPS est suffisante, tant que la valeur secrète est suffisamment longue et non devinable. Pour les intégrations critiques en matière de sécurité, par exemple les prestataires de paiement, il est recommandé d'ajouter une liste blanche d'IP ou une vérification de signature comme HMAC dans un nœud Code en aval.

Pourquoi mon adresse IP mise en liste blanche est-elle quand même bloquée ?

Cela vient généralement d'un N8N_PROXY_HOPS manquant ou mal défini, lorsque n8n fonctionne derrière un reverse proxy. Sans cette variable, n8n ne voit pas l'adresse IP réelle de l'expéditeur, mais l'adresse interne du proxy, et la compare à tort à la liste blanche.

Puis-je placer plusieurs workflows sur le même chemin de webhook ?

Non, selon la documentation n8n, un seul webhook peut être enregistré par combinaison de chemin et de méthode HTTP à la fois. Pour plusieurs déclencheurs sur le même chemin, vous devez utiliser des méthodes HTTP différentes ou adapter le chemin.

Que se passe-t-il si je continue à utiliser l'URL de test après le développement ?

L'URL de test n'est active que pendant 120 secondes après avoir cliqué sur Listen for Test Event et affiche les données dans l'éditeur. Après la publication du workflow, les systèmes appelants doivent être basculés vers l'URL de production, sinon leurs requêtes n'aboutissent nulle part.

Dois-je utiliser JWT Auth si le service appelant ne le propose pas ?

Non, la méthode d'authentification dépend toujours de ce que le service appelant prend réellement en charge. Si un service ne propose qu'une simple clé API, Header Auth convient mieux que JWT Auth, qui nécessite un jeton signé.