Un Webhook n8n sert à démarrer un workflow lorsqu’un service externe appelle une URL. Voici comment envoyer un premier POST, protéger son point d’entrée et passer de l’URL de test à celle de production. Guide documentaire : les commandes proposées n’ont pas été exécutées sur une instance n8n lors de sa rédaction.
Si vous découvrez l’automatisation, vous pouvez aussi replacer ce guide dans la logique des logiciels d’automatisation clés : un webhook n’est pas un outil magique, c’est une porte d’entrée HTTP qui lance une suite d’actions.
Principe du Webhook dans n8n
Dans n8n, le nœud Webhook est un nœud déclencheur. Il peut recevoir des données depuis une application ou un script externe, puis démarrer le workflow avec ces données. Le nœud accepte plusieurs méthodes HTTP, dont POST, GET, PUT, PATCH et DELETE. Pour un premier test, POST est souvent le plus lisible, car il permet d’envoyer un corps JSON avec des champs simples.
Le point important : l’appel HTTP déclenche le workflow, mais la réponse reçue par l’appelant ne signifie pas toujours que tout le traitement métier est terminé. Selon la configuration de réponse, n8n peut répondre immédiatement ou attendre un nœud dédié de réponse. Il faut donc distinguer la réussite de la réception du webhook et la réussite complète du workflow.
Préparer le workflow et son authentification
- Ouvrez votre instance n8n, créez un workflow vide et ajoutez le nœud Webhook comme déclencheur.
- Dans HTTP Method, choisissez POST. Dans Path, saisissez
lead-demo, sans réutiliser un chemin déjà affecté à un autre webhook de même méthode. - Dans Authentication, choisissez Header Auth et créez un credential. Son champ Name doit contenir
X-Demo-Token; son champ Value, un secret aléatoire propre à ce test. - Pour ce premier essai, choisissez Respond → Immediately. La réponse confirmera le démarrage, pas la réussite des actions suivantes.
Copiez l’URL réellement affichée par n8n : le domaine et les préfixes peuvent varier avec votre hébergement. L’exemple ci-dessous utilise un domaine fictif, à remplacer ; ne l’envoyez pas tel quel.
Test URL : écouter un événement de développement
Le nœud Webhook affiche une URL de test. Elle sert pendant la construction du workflow. D’après la documentation n8n, le webhook de test est enregistré lorsque vous cliquez sur Listen for Test Event ou lorsque vous exécutez le workflow si celui-ci n’est pas actif. L’intérêt est simple : vous envoyez une requête, n8n affiche les données reçues dans l’éditeur, puis vous ajustez les nœuds suivants.
Cette URL de test n’est pas celle à donner durablement à un service externe. Elle est faite pour vérifier le format reçu : champs JSON, en-têtes, méthode HTTP, chemin et éventuels paramètres. Si l’appel ne fonctionne pas, vérifiez d’abord que l’écoute de test est bien lancée au moment de la requête.
Production URL : publier avant d’appeler durablement
Le même nœud propose aussi une URL de production. La documentation actuelle parle de publier le workflow pour enregistrer le webhook de production. Une fois publié, l’appel de cette URL ne renvoie pas automatiquement les données dans l’éditeur comme pendant un test. Pour consulter ce qui s’est passé, il faut regarder les exécutions du workflow.
En pratique, utilisez l’URL de test pour construire, puis basculez seulement l’intégration externe sur l’URL de production lorsque le workflow est publié et que les erreurs de format sont comprises. Si vous collez trop tôt l’URL de production dans un outil tiers, vous risquez de diagnostiquer le mauvais problème : workflow non publié, ancienne URL, mauvaise méthode ou authentification absente.
Créer un POST fictif avec JSON
Pour un premier essai, choisissez la méthode POST dans le nœud Webhook. Donnez un chemin explicite, par exemple lead-demo, puis démarrez l’écoute de test. Envoyez ensuite une requête avec des données fictives. N’utilisez jamais une vraie clé, un vrai email client ou un secret de production dans un exemple de test.
curl -X POST "https://votre-instance.example/webhook-test/lead-demo" -H "Content-Type: application/json" -H "X-Demo-Token: valeur-fictive-a-remplacer" -d '{"email":"demo@example.com","source":"formulaire-test","consent":true}'Dans les nœuds suivants, les données du corps JSON sont accessibles via les champs reçus. Par exemple, l’email envoyé dans cet exemple peut être lu comme une donnée du body, typiquement avec une expression comme {{ $json.body.email }} selon la structure exacte affichée par votre exécution. Le bon réflexe est de regarder l’objet réellement reçu dans l’éditeur n8n avant de figer une expression.
Ajouter une authentification Header
n8n documente plusieurs méthodes d’authentification pour le Webhook, dont Basic auth, Header auth, JWT auth ou aucune authentification. Pour un premier flux entre deux outils que vous contrôlez, Header auth est souvent lisible : l’appelant ajoute un en-tête nommé, par exemple X-Demo-Token, et n8n vérifie la valeur attendue via les credentials configurés.
Remplacez valeur-fictive-a-remplacer par votre secret de test, identique au credential. Un secret réel ne doit pas être publié dans un article, dans un dépôt public ou dans une capture. Stockez-la dans le système de secrets adapté à votre environnement. Côté test, vous pouvez volontairement envoyer une mauvaise valeur fictive pour vérifier que n8n refuse l’appel au lieu de lancer le workflow.
Répondre au webhook sans confondre accusé et traitement fini
Si vous avez besoin de contrôler précisément la réponse HTTP, n8n propose le nœud Respond to Webhook. Il peut répondre avec du JSON, du texte, un statut HTTP, une redirection, un fichier ou aucun contenu. Pour l’utiliser, sélectionnez Respond → Using Respond to Webhook Node dans le déclencheur, reliez le nœud Respond to Webhook après le traitement voulu et choisissez Respond With → JSON pour une réponse JSON. Si vous choisissez à la place When Last Node Finishes, le déclencheur peut renvoyer directement la sortie du dernier nœud sans ce nœud de réponse supplémentaire.
Attention à la promesse fonctionnelle : retourner {"ok":true} peut seulement indiquer que la requête est reçue, pas que l’email est envoyé, que la facture est créée ou que le CRM est à jour. Pour éviter les faux positifs, choisissez une réponse claire : accusé de réception immédiat ou résultat final après les étapes critiques.
Erreurs fréquentes à vérifier
- 404 : mauvaise URL, workflow non publié, chemin modifié ou URL de test appelée sans écoute active.
- 401/403 : authentification absente, nom d’en-tête incorrect ou valeur invalide.
- Méthode incorrecte : vous appelez en GET alors que le nœud attend POST.
- JSON invalide : guillemets cassés, virgule en trop ou mauvais
Content-Type. - Doublons : un service externe peut réessayer un appel. Prévoyez un identifiant d’événement ou une logique d’idempotence.
- Payload trop gros : la limite documentée est de 16 Mo par défaut ; en auto-hébergement,
N8N_PAYLOAD_SIZE_MAXpermet de l’ajuster. Augmenter la limite demande aussi de vérifier le proxy et la mémoire disponible.
Checklist avant production
- Tester la requête sur l’URL de test avec des données fictives.
- Vérifier dans n8n la structure réelle du body et des headers.
- Ajouter une authentification adaptée, au minimum pour éviter une URL publique ouverte.
- Définir ce que signifie la réponse HTTP : reçu ou terminé.
- Publier le workflow, puis basculer l’outil externe vers l’URL de production.
- Contrôler les exécutions de production après les premiers appels.
Pour aller plus loin
Pour revenir au principe sans les réglages du produit, consultez la définition d’un webhook. La fiche API REST : ressources et méthodes HTTP aide à distinguer notification reçue et appel sortant.
