n8n webhook ne fonctionne pas ? Dans la majorité des cas, le problème vient de l’URL appelée, du mode test qui a expiré, d’un reverse proxy mal configuré ou d’un workflow qui n’est pas activé. Commencez par copier l’URL de production du nœud Webhook, activez le workflow, puis envoyez une requête avec curl. Si la réponse reste en erreur, le diagnostic ci-dessous permet d’isoler la couche fautive en quelques minutes.

Un webhook est une URL HTTP qui déclenche un workflow lorsqu’un service externe lui envoie une requête. n8n distingue une URL de test, temporaire et visible dans l’éditeur, d’une URL de production, utilisable quand le workflow est actif. Cette différence explique une grande partie des erreurs rencontrées avec Stripe, GitHub, WordPress, Make ou une application maison.

Identifier le symptôme exact du webhook n8n

Ne cherchez pas d’abord une solution dans les identifiants. Notez le code HTTP, le message affiché par le service appelant et la présence éventuelle d’une exécution dans n8n. Un code 404 indique généralement un chemin incorrect ou un workflow inactif. Un délai d’attente pointe plutôt vers le réseau ou le proxy. Un code 401 ou 403 concerne l’authentification. Une réponse 200 sans exécution peut venir d’un mauvais nœud, d’un filtre ou d’une requête envoyée à l’URL de test.

# Remplacez l’URL par l’URL de production affichée par n8n
curl -i -X POST 'https://n8n.exemple.fr/webhook/commande' 
  -H 'Content-Type: application/json' 
  -d '{"event":"test","order_id":123}'

Le premier contrôle consiste donc à reproduire l’appel en dehors du service tiers. Cette méthode retire les hypothèses liées à Stripe ou à votre formulaire et montre la réponse réelle de n8n. Conservez les en-têtes et le corps envoyés, car une vérification sérieuse doit distinguer une absence de requête d’une donnée mal formée.

Choisir la bonne URL, test ou production

Le nœud Webhook présente deux adresses. L’URL de test sert pendant la construction du workflow. Pour l’utiliser, cliquez sur « Écouter l’événement de test » dans n8n, puis envoyez immédiatement la requête. Elle n’est pas destinée à une intégration permanente. L’URL de production fonctionne uniquement lorsque le workflow est activé. Copier l’URL de test dans Stripe ou GitHub donne donc souvent l’impression que n8n est cassé.

Ouvrez le nœud Webhook, sélectionnez la méthode HTTP attendue et comparez le chemin caractère par caractère. commande, commandes et une majuscule dans le chemin sont trois routes différentes selon la configuration. Vérifiez aussi que le service externe utilise bien POST, PUT ou GET selon votre choix. Certains outils envoient un POST par défaut alors que le nœud n8n attend un GET.

# Test de production avec un en-tête d’autorisation
curl -i -X POST 'https://n8n.exemple.fr/webhook/commande' 
  -H 'Content-Type: application/json' 
  -H 'X-Webhook-Secret: secret-de-test' 
  --data-binary @payload.json

Pour une intégration durable, utilisez l’URL de production, activez le workflow et relancez l’appel. Si vous modifiez le chemin, mettez à jour l’URL dans le service appelant. La documentation officielle de n8n sur les Webhook nodes détaille les modes et les réponses possibles, sans rel= »nofollow » car il s’agit d’une ressource externe de référence mais non commerciale.

Activer le workflow et vérifier la méthode HTTP

Un workflow n8n peut être parfaitement construit et ne rien recevoir parce qu’il est désactivé. Le bouton d’activation se trouve en haut de l’éditeur. Après chaque modification importante du nœud Webhook, désactivez puis réactivez le workflow si l’interface n’a pas rafraîchi son état. Regardez ensuite la liste des exécutions, en séparant les exécutions réussies, échouées et celles qui n’ont jamais démarré.

Contrôlez aussi les options de réponse. Le mode « On Received » renvoie rapidement une réponse au service appelant, tandis que « When Last Node Finishes » attend la fin du workflow. Un traitement lent peut faire expirer Stripe ou votre application même si n8n continue le travail. Pour une automatisation longue, préférez une réponse immédiate avec un identifiant de suivi, puis traitez la suite de façon asynchrone.

# Vérifier rapidement le code HTTP et le temps total
curl -sS -o /tmp/n8n-response.txt -w 'HTTP %{http_code} en %{time_total}sn' 
  -X POST 'https://n8n.exemple.fr/webhook/commande' 
  -H 'Content-Type: application/json' 
  -d '{"healthcheck":true}'
cat /tmp/n8n-response.txt

Si n8n affiche une exécution mais que le service tiers signale une erreur, le souci est probablement dans le format de réponse ou le délai. Si aucune exécution n’apparaît, remontez vers l’URL, le DNS, le proxy et le pare-feu. Cette séparation évite de modifier inutilement les étapes internes du workflow.

Corriger le reverse proxy, HTTPS et les variables n8n

Une installation n8n derrière Nginx, Traefik, Caddy ou un proxy de fournisseur doit connaître son URL publique. Les variables WEBHOOK_URL, N8N_EDITOR_BASE_URL et N8N_PROTOCOL doivent correspondre à l’adresse réellement accessible depuis Internet. Une URL générée avec un nom de conteneur, un port interne ou HTTP au lieu de HTTPS ne peut pas être appelée par un service externe.

environment:
  N8N_HOST: n8n.exemple.fr
  N8N_PROTOCOL: https
  N8N_PORT: 5678
  WEBHOOK_URL: https://n8n.exemple.fr/
  N8N_EDITOR_BASE_URL: https://n8n.exemple.fr/
  N8N_PROXY_HOPS: 1

Après une modification des variables, recréez le conteneur et vérifiez les journaux. Le proxy doit transmettre les requêtes vers le port interne de n8n et conserver les en-têtes utiles, notamment Host, X-Forwarded-For et X-Forwarded-Proto. Un certificat expiré, un enregistrement DNS encore ancien ou un pare-feu qui bloque le port 443 produit souvent un timeout avant même que n8n puisse journaliser la requête.

Si n8n tourne sur un réseau local, l’URL localhost ne fonctionne pas pour GitHub ou Stripe. Il faut une adresse publique, un tunnel temporaire ou un relais. Pour un usage de production, privilégiez un domaine avec TLS, des sauvegardes et une règle réseau restrictive. Notre guide pour installer n8n avec Docker Compose explique la base PostgreSQL, le HTTPS et les mises à jour dans une installation durable.

Vérifier le corps JSON et les en-têtes reçus

Un webhook peut être atteint tout en semblant inutilisable si la charge utile n’est pas celle attendue. Dans l’exécution n8n, ouvrez l’entrée du nœud et inspectez headers, params et body. Un envoi application/x-www-form-urlencoded ne se lit pas comme un JSON. Une signature HMAC absente ou calculée sur un corps déjà transformé provoque aussi un refus d’authentification.

// Dans un nœud Code n8n, inspecter sans exposer un secret
const body = $json.body ?? {};
const headers = $json.headers ?? {};
return [{
  json: {
    event: body.event ?? null,
    contentType: headers['content-type'] ?? null,
    hasSignature: Boolean(headers['x-webhook-signature'])
  }
}];

Ne copiez pas les clés API ni les données personnelles dans un outil de test public. Comparez le nom exact des champs avec le schéma attendu, puis ajoutez une étape de validation. Vous pouvez retourner une erreur explicite si event manque, au lieu de laisser une étape suivante échouer avec un message peu lisible.

Diagnostiquer l’authentification et les signatures

Selon le service, l’authentification peut utiliser une URL secrète, un en-tête, une authentification Basic ou une signature calculée. Configurez la même convention des deux côtés. Un secret dans l’URL est simple mais apparaît dans certains journaux. Un en-tête dédié est généralement préférable. Pour une intégration sensible, vérifiez la signature sur le corps brut et comparez avec une fonction de comparaison constante.

const crypto = require('crypto');
const rawBody = JSON.stringify($json.body ?? {});
const received = $json.headers?.['x-webhook-signature'] ?? '';
const expected = crypto
  .createHmac('sha256', $env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
return [{ json: { valid: received === expected } }];

Dans n8n, préférez les credentials et les variables d’environnement aux secrets écrits en clair dans un nœud. Si le fournisseur signe le corps original, la sérialisation JSON locale peut changer l’ordre ou les espaces. Utilisez alors le mode de réception et la méthode de vérification recommandés par le fournisseur, plutôt qu’un calcul approximatif.

Éviter les doublons, délais et erreurs côté fournisseur

Certains fournisseurs réessaient un webhook quand n8n ne répond pas assez vite. Vous pouvez alors obtenir plusieurs commandes ou plusieurs tickets pour un seul événement. Ajoutez un identifiant d’événement et rendez l’opération idempotente. Stockez les identifiants déjà traités dans une base ou un cache avec une durée d’expiration. Un délai de réponse court et une file de traitement réduisent également les nouvelles tentatives.

Pour distinguer une panne n8n d’une panne du fournisseur, envoyez le même payload avec curl, vérifiez le code HTTP, puis consultez les journaux du reverse proxy. Dans le tableau de bord du service appelant, cherchez la réponse complète et l’historique des tentatives. Un 200 reçu par le fournisseur ne garantit pas que toutes les étapes du workflow ont réussi, il confirme seulement la réponse HTTP.

Pour choisir entre n8n et une autre plateforme selon la gestion des erreurs, consultez notre comparatif n8n et Make. Le point important est de décider où vivent les reprises, les journaux et la déduplication, pas seulement de comparer le nombre de connecteurs.

Checklist finale quand n8n webhook ne fonctionne pas

Suivez cette séquence sans sauter d’étape. Elle permet de localiser rapidement le problème et de conserver une trace utile pour un hébergeur ou un fournisseur tiers.

  1. Copiez l’URL de production directement depuis le nœud Webhook.
  2. Activez le workflow et confirmez que le nœud attend la bonne méthode HTTP.
  3. Reproduisez l’appel avec curl et un petit JSON sans donnée sensible.
  4. Comparez le code HTTP, le temps de réponse et la présence d’une exécution n8n.
  5. Vérifiez DNS, certificat, port 443, reverse proxy et variables d’URL publique.
  6. Inspectez les en-têtes, le type de contenu et le chemin de la charge utile.
  7. Contrôlez le secret ou la signature, puis testez les reprises et les doublons.

Si l’erreur est apparue après une mise à jour, comparez la configuration du conteneur, les journaux et les versions du proxy. Évitez de désactiver durablement l’authentification pour « faire marcher » le webhook. Un test isolé avec un secret temporaire est plus sûr et plus facile à supprimer.

FAQ sur les webhooks n8n

Pourquoi l’URL de test n8n ne répond-elle plus ?

L’URL de test n8n ne répond plus lorsque le mode d’écoute n’est pas actif ou lorsque sa fenêtre de test est terminée. Cliquez sur « Écouter l’événement de test », envoyez ensuite la requête, puis utilisez l’URL de production et activez le workflow pour une intégration permanente.

Pourquoi mon webhook n8n renvoie-t-il une erreur 404 ?

Une erreur 404 indique le plus souvent un chemin incorrect, une URL de test utilisée en production ou un workflow désactivé. Copiez à nouveau l’URL depuis le nœud, vérifiez la méthode HTTP et contrôlez que le proxy transmet bien le chemin /webhook/.

Pourquoi n8n reçoit-il le webhook mais pas les données JSON ?

n8n reçoit le webhook sans données JSON quand le service envoie un autre type de contenu, quand le JSON est invalide ou quand les champs sont placés dans les paramètres. Inspectez headers, body et params dans l’exécution, puis forcez l’en-tête Content-Type: application/json.

Comment rendre un webhook n8n sécurisé ?

Rendez un webhook n8n plus sûr avec une URL difficile à deviner, un secret dans un en-tête, une vérification de signature, HTTPS, une validation des champs et une protection contre les doublons. Ne journalisez pas les tokens et limitez les droits du compte utilisé par le workflow.

Pourquoi le webhook n8n fonctionne avec curl mais pas avec Stripe ?

Le webhook n8n peut fonctionner avec curl mais pas avec Stripe si l’URL, la méthode, la signature ou le délai de réponse diffère. Comparez l’événement Stripe réel avec votre test, configurez la signature Stripe prévue par n8n et renvoyez une réponse rapide avant le traitement long.

Sources

G
WP Admin Lab

Architecte web full-stack. WordPress, performance, data et sécurité. Notes de terrain, tests reproductibles et retours d'expérience.