Qu'est-ce qu'un webhook et pourquoi c'est important

La plupart des intégrations API fonctionnent en pull : votre workflow s'exécute selon un planning, appelle un service externe et récupère ce qui a changé depuis la dernière vérification. Les webhooks inversent ce modèle. Au lieu que vous posiez la question, c'est le service externe qui vous pousse les données dès qu'un événement se produit — un paiement est validé, un formulaire est soumis, un dépôt reçoit un nouveau commit. Le résultat : une réaction quasi instantanée sans aucun overhead de polling.

n8n dispose d'un nœud Webhook intégré qui transforme n'importe quel workflow en point de terminaison HTTP. Lorsque ce point de terminaison reçoit une requête, le workflow se déclenche immédiatement. Cette leçon vous guide pas à pas dans sa mise en place, le traitement du payload reçu et l'envoi d'une réponse correcte à l'appelant.

Configuration du nœud Webhook

Glissez un nœud Webhook sur le canvas et définissez-le comme déclencheur (premier nœud). Les deux paramètres à configurer immédiatement sont la HTTP Method et le Path.

La HTTP Method est presque toujours POST — c'est ce qu'envoient toutes les grandes plateformes. N'utilisez GET que lorsque le tiers le documente explicitement (certaines poignées de main de vérification utilisent GET).

Le Path est le slug unique qui identifie ce workflow. n8n génère un UUID par défaut, mais vous pouvez définir quelque chose de lisible comme /stripe-events ou /github-push. L'URL complète affichée par n8n ressemble à ceci :

https://your-n8n-instance.com/webhook/stripe-events

Vous collez cette URL dans les paramètres webhook de la plateforme tierce — tableau de bord Stripe, paramètres du dépôt GitHub, Typeform, quel que soit le service.

n8n fournit deux URL de webhook par nœud : une Test URL et une Production URL. La Test URL n'est active que lorsque vous êtes dans l'éditeur avec le workflow ouvert et à l'écoute. La Production URL n'est active que lorsque le workflow est sauvegardé et activé. Ne donnez jamais votre Test URL à un fournisseur pour une intégration en production — elle cesse de fonctionner dès que vous fermez l'onglet du navigateur.

Réception et analyse du payload

Une fois le webhook déclenché, les données entrantes arrivent dans la sortie du nœud Webhook. n8n analyse automatiquement les corps JSON. Ainsi, si Stripe envoie un événement payment_intent.succeeded, vous accédez au montant du paiement directement dans les nœuds suivants sous forme d'expression :

{{ $json.data.object.amount }}

Pour les corps encodés en formulaire (certains services plus anciens envoient Content-Type: application/x-www-form-urlencoded), n8n les analyse également automatiquement dans le même objet $json.

Les en-têtes sont également disponibles, ce qui est important pour la vérification de signature. Stripe, GitHub et la plupart des plateformes sérieuses signent leurs payloads de webhook avec un secret HMAC afin que vous puissiez confirmer que la requête provient bien d'elles. Dans n8n, vous pouvez lire l'en-tête de signature dans un nœud Code et la vérifier :

const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = $input.first().binary?.data
  ? Buffer.from($input.first().binary.data, 'base64').toString()
  : JSON.stringify($input.first().json);
const signature = $input.first().headers['x-hub-signature-256'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');
if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}
return $input.all();

Validez toujours les signatures sur les workflows de production qui déclenchent des actions sensibles — envoi d'e-mails, modification d'enregistrements, facturation d'utilisateurs.

Répondre à l'appelant

Certaines plateformes exigent une réponse HTTP spécifique, et pas seulement le 200 OK par défaut. Stripe attend un 200 en quelques secondes, sinon il relance. GitHub attend 200. Certains systèmes comme Typeform ou des services internes personnalisés attendent en retour un corps JSON confirmant la réception.

Dans les paramètres du nœud Webhook, réglez Response Mode sur Last Node. Le dernier nœud de votre workflow contrôle alors ce qui est renvoyé. Associez-le à un nœud Respond to Webhook en fin de chaîne et configurez-le :

{
  "statusCode": 200,
  "body": { "received": true, "id": "={{ $json.id }}" }
}

Si votre workflow effectue des traitements lourds — écritures en base, envois d'e-mails, appels à d'autres API — et que vous devez quand même répondre rapidement, utilisez Response Mode : Immediately dans le nœud Webhook. n8n renvoie 200 immédiatement et continue à exécuter le reste du workflow en arrière-plan. Le compromis : vous ne pouvez pas envoyer de corps de réponse dynamique, mais l'appelant n'expire jamais.

Erreurs courantes à éviter

Utiliser la Test URL en production est l'erreur la plus fréquente. Le workflow devient silencieux dès que vous fermez l'éditeur, et personne ne s'en aperçoit avant que des événements soient perdus.

Ne pas gérer les retries est un autre manquement. Stripe relance les webhooks en échec jusqu'à 72 heures. Si votre workflow n'est pas idempotent — c'est-à-dire que l'exécuter deux fois sur le même événement provoque un enregistrement en doublon ou une double facturation — vous devez vérifier si vous avez déjà traité un ID d'événement donné avant toute écriture.

Ignorer le timeout de réponse provoque des échecs silencieux. Si votre workflow prend 30 secondes et que l'appelant attend une réponse en 5 secondes, il marque la livraison comme échouée et relance, même si votre workflow finit par réussir. Répondez immédiatement, soit en optimisant le chemin de traitement.

Résumé

Les webhooks permettent à des services tiers de pousser des événements vers n8n en temps réel, supprimant ainsi le besoin de polling planifié. Vous configurez un nœud Webhook avec un path et une méthode HTTP, collez la Production URL dans les paramètres du fournisseur, puis accédez au payload via $json dans les nœuds en aval. La vérification de signature protège contre les requêtes usurpées, et le nœud Respond to Webhook ou le mode Immediately vous donnent le contrôle de ce que l'appelant reçoit en retour. Maîtriser ces détails — URL correcte, vérification de signature, idempotence, timing de réponse — fait la différence entre une intégration fragile et une intégration fiable en production.