Webhooks expliqués simplement : comprendre et utiliser les webhooks

Un webhook est un mécanisme qui permet à un système d'envoyer automatiquement des données vers un autre système dès qu'un événement se produit. Pas de requête répétée, pas d'attente : l'information arrive d'elle-même, en temps réel.

Ce guide couvre le fonctionnement technique des webhooks, les différences avec le polling API, les bonnes pratiques de sécurité, et des implémentations concrètes.

Qu'est-ce qu'un webhook ?

Un webhook (littéralement « crochet web ») est une URL configurable qui reçoit des requêtes HTTP automatiques lorsqu'un événement spécifique se déclenche dans une application source. On appelle aussi cela un « HTTP callback » ou une « notification push web ».

Le principe est simple :

Configuration : on fournit une URL de réception (endpoint) à un service tiers.
Déclenchement : un événement se produit côté source (nouvelle commande, paiement validé, etc.).
Envoi : le service source envoie une requête HTTP (généralement POST) vers l'URL configurée, contenant les données de l'événement au format JSON.
Traitement : le serveur récepteur traite la payload et exécute les actions nécessaires.

Anatomie d'un webhook

Une requête webhook typique se compose de :

Méthode HTTP : POST dans la grande majorité des cas.
URL cible : l'endpoint configuré par le récepteur.
Headers : métadonnées comme le type de contenu (Content-Type: application/json), un identifiant d'événement, et une signature pour la vérification.
Body (payload) : les données de l'événement au format JSON.

Exemple de payload :

{
  "id": "evt_01HXYZ123",
  "type": "payment.completed",
  "timestamp": "2026-04-14T20:15:00Z",
  "data": {
    "amount": 99.99,
    "currency": "EUR",
    "customer_id": "cust_42"
  }
}

Webhook vs API polling : quelle différence ?

La différence fondamentale réside dans qui initie la communication.

Le polling API (requête répétée)

Le polling consiste à interroger régulièrement un serveur pour vérifier si de nouvelles données sont disponibles.

# Le client interroge toutes les 30 secondes
while true; do
  curl -s https://api.example.com/orders?since=last_check
  sleep 30
done

Problèmes du polling :

Gaspillage de ressources : la majorité des requêtes retournent des données vides (pas de changement).
Latence : le délai entre l'événement et sa détection dépend de l'intervalle de polling. Avec un intervalle de 30 secondes, la latence moyenne est de 15 secondes.
Charge serveur : des milliers de clients en polling créent une charge inutile sur le serveur source.
Rate limiting : les API limitent souvent le nombre de requêtes, ce qui oblige à espacer les interrogations.

Le webhook (notification push)

Avec un webhook, le serveur source pousse les données vers le client uniquement quand un événement se produit.

Avantages du webhook :

Temps réel : les données arrivent instantanément après l'événement.
Efficacité : pas de requêtes inutiles, pas de réponse vide.
Scalabilité : la charge sur le serveur source est proportionnelle aux événements réels, pas au nombre de clients.
Économie de bande passante : on ne transfère que les données utiles.

Tableau comparatif

Critère	Polling API	Webhook
Initiateur	Client	Serveur source
Temps réel	Non (latence = intervalle)	Oui (quasi instantané)
Charge serveur	Élevée (requêtes constantes)	Faible (uniquement sur événement)
Complexité côté client	Faible (boucle simple)	Moyenne (endpoint à maintenir)
Fiabilité	Bonne (client contrôle)	Moyenne (retry, gestion des échecs)
Cas d'usage idéal	Données rarement mises à jour	Événements fréquents et critiques

Cas d'usage concrets des webhooks

1. Paiements et e-commerce

Quand un client effectue un paiement sur Stripe, PayPal ou un autre prestataire, un webhook notifie le système de commande :

payment.completed → confirmer la commande et envoyer l'email de confirmation.
payment.failed → annuler la réservation et notifier le client.
refund.processed → mettre à jour le stock et la comptabilité.

2. Intégration CI/CD

Les plateformes comme GitHub, GitLab ou Bitbucket envoient des webhooks lors de chaque push, pull request ou merge :

push → déclencher un pipeline de build et de tests.
pull_request.opened → lancer l'analyse de code statique.
deployment.success → notifier l'équipe sur Slack.

3. SaaS et automatisation

Les outils comme Zapier, Make (Integromat) ou n8n reposent massivement sur les webhooks pour connecter des services entre eux :

Un nouveau lead sur HubSpot → création d'une tâche dans Notion.
Un email marqué « important » dans Gmail → notification SMS via Twilio.
Une nouvelle ligne dans Google Sheets → mise à jour d'un CRM.

4. Notifications temps réel

Les systèmes de monitoring et d'alerte utilisent des webhooks pour notifier instantanément :

Un serveur tombe → alerte PagerDuty → appel automatique de l'ingénieur de garde.
Un seuil de CPU dépassé → message Slack.
Un certificat SSL expire bientôt → email à l'admin.

Comment implémenter un webhook récepteur

Créer l'endpoint

Voici un exemple en Node.js avec Express :

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

// Clé secrète partagée avec l'expéditeur
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhooks/payments', (req, res) => {
  // 1. Vérifier la signature
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const expectedSig = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).json({ error: 'Signature invalide' });
  }

  // 2. Traiter l'événement
  const { type, data } = req.body;

  switch (type) {
    case 'payment.completed':
      // Confirmer la commande
      handlePaymentCompleted(data);
      break;
    case 'payment.failed':
      // Gérer l'échec
      handlePaymentFailed(data);
      break;
    default:
      console.log(`Événement non géré : ${type}`);
  }

  // 3. Répondre immédiatement (200 OK)
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook listener sur le port 3000');
});

Points clés de l'implémentation

Répondre rapidement : l'endpoint doit retourner un statut 200 OK le plus vite possible. Le traitement lourd (envoi d'emails, mise à jour de base de données) doit être asynchrone (file d'attente, worker).

Gérer les idempotences : un même webhook peut être envoyé plusieurs fois (retry). Le système doit être capable de traiter un événement en doublon sans effet secondaire indésirable. Utiliser l'ID unique de l'événement (id) comme clé de déduplication.

Journaliser : stocker chaque webhook reçu (payload, timestamp, statut de traitement) pour le debugging et l'audit.

Comment implémenter un webhook émetteur

Architecture d'envoi

async function sendWebhook(url, payload, secret, retries = 3) {
  const timestamp = Date.now();
  const signature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex');

  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Webhook-Signature': signature,
          'X-Webhook-Timestamp': String(timestamp),
          'X-Webhook-ID': crypto.randomUUID(),
        },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(10000), // Timeout 10s
      });

      if (response.ok) {
        console.log(`Webhook envoyé avec succès (tentative ${attempt})`);
        return true;
      }

      console.warn(`Tentative ${attempt} : statut ${response.status}`);
    } catch (error) {
      console.warn(`Tentative ${attempt} échouée :`, error.message);
    }

    // Backoff exponentiel
    if (attempt < retries) {
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
    }
  }

  console.error(`Webhook échoué après ${retries} tentatives`);
  return false;
}

Stratégie de retry

Backoff exponentiel : attendre 1s, 2s, 4s, 8s entre les tentatives.
Maximum de tentatives : 3 à 5 retries avant d'abandonner.
Timeout : 5 à 10 secondes par tentative.
Dead letter queue : stocker les webhooks définitivement échoués pour analyse et rejeu manuel.

Sécurité des webhooks

Vérification de signature

La signature HMAC-SHA256 est le standard de sécurité des webhooks. Le principe :

L'expéditeur et le récepteur partagent une clé secrète.
L'expéditeur génère un HMAC du payload avec cette clé.
Le récepteur recalcule le HMAC et le compare à celui reçu.

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Utiliser timingSafeEqual pour éviter les attaques par timing.

Autres mesures de sécurité

HTTPS obligatoire : jamais de webhook sur HTTP en production.
Restriction d'IP : n'accepter les webhooks que depuis les plages d'IP connues de l'expéditeur.
Rotation des secrets : changer la clé secrète périodiquement.
Validation du payload : vérifier la structure et les types de données reçus.
Rate limiting : limiter le nombre de requêtes par IP pour éviter le DDoS.
Journalisation : logger toutes les tentatives (réussies ou échouées) avec l'IP source.

Gestion des échecs et fiabilité

Les webhooks ne sont pas garantis à 100%. Réseau instable, serveur en maintenance, timeout — de nombreuses causes peuvent faire échouer une livraison.

Architecture de fiabilité

File d'attente : ne jamais envoyer un webhook directement depuis le processus principal. Le passer par une file (Redis, RabbitMQ, SQS).
Retry avec backoff : comme décrit ci-dessus.
Monitoring : surveiller le taux de livraison et alerter en cas de chute.
Dashboard : interface pour visualiser les webhooks envoyés, leur statut, et rejouer les échecs.
Endpoint de santé : vérifier que l'URL cible est joignable avant d'envoyer.

Endpoint de vérification (handshake)

Certains fournisseurs implémentent un handshake lors de la configuration :

Le fournisseur envoie une requête GET avec un challenge token.
Le récepteur doit répondre avec ce token hashé.

GET /webhooks?challenge=ch_abc123
→ Response: ch_abc123 (ou HMAC du challenge)

Cela prouve que le récepteur contrôle bien l'URL configurée.

Outils populaires utilisant les webhooks

Plateformes de paiement

Stripe : webhooks pour paiements, refunds, disputes, subscriptions.
PayPal : notifications IPN et webhooks API v2.
Square : webhooks pour transactions, inventaire, clients.

Développement et CI/CD

GitHub : events pour push, pull requests, issues, deployments.
GitLab : webhooks système et projet, supporte les triggers de pipeline.
Jenkins : Generic Webhook Trigger plugin pour déclencher des builds.

Communication

Slack : incoming webhooks pour poster des messages dans des canaux.
Discord : webhooks pour envoyer des embeds et des messages.
Telegram : Bot API avec webhook mode pour les bots de chat.

Automatisation

Zapier : connecteurs basés sur des webhooks pour lier des centaines de services.
Make (Integromat) : scénarios d'automatisation déclenchés par webhooks.
n8n : outil open source d'automatisation avec nœud webhook natif.

Tester et déboguer les webhooks

Outils locaux

ngrok : expose un tunnel public vers un localhost, idéal pour tester des webhooks en développement.

ngrok http 3000
# → Forwarding https://abc123.ngrok.io → http://localhost:3000

Configurer l'URL ngrok comme endpoint de webhook pendant le développement.

Webhook.site : service gratuit qui génère une URL unique et affiche en temps réel toutes les requêtes reçues. Parfait pour inspecter les payloads.

Bonnes pratiques de test

Logger systématiquement : enregistrer le payload brut, les headers, et le statut de réponse.
Mock server : utiliser des outils comme Mockoon ou WireMock pour simuler un endpoint.
Tests unitaires : écrire des tests pour chaque type d'événement traité.
Tests de charge : vérifier le comportement sous un volume élevé de webhooks simultanés.
Monitoring en production : tableau de bord avec le nombre de webhooks reçus, le taux de succès, et le temps de traitement moyen.

FAQ

Qu'est-ce qu'un webhook en termes simples ?

Un webhook est une URL qui reçoit automatiquement des données d'un autre service dès qu'un événement se produit. Au lieu d'aller chercher l'information (polling), l'information vient seule, comme une notification push.

Quelle est la différence entre un webhook et une API REST ?

Une API REST fonctionne à la demande : le client envoie une requête et reçoit une réponse. Un webhook fonctionne en mode push : le serveur envoie les données au client sans que celui-ci n'ait besoin de demander quoi que ce soit. L'API REST est initiée par le client, le webhook par le serveur.

Les webhooks sont-ils sécurisés ?

Oui, à condition de suivre les bonnes pratiques : utiliser HTTPS, vérifier la signature HMAC-SHA256, restreindre les IP sources, et valider les payloads reçus. Sans ces mesures, un webhook expose un endpoint public potentiellement vulnérable.

Que faire si un webhook n'arrive pas à destination ?

Implémenter un mécanisme de retry avec backoff exponentiel, surveiller le taux de livraison, et disposer d'une dead letter queue pour les échecs définitifs. Certains fournisseurs proposent aussi une API pour relister les événements manqués.

Un webhook peut-il être envoyé plusieurs fois ?

Oui, et c'est même un comportement attendu. Les expéditeur implémentent des retentatives automatiques en cas de non-réponse (timeout, erreur 5xx). Le récepteur doit être idempotent : traiter un même événement deux fois sans effet secondaire indésirable, généralement en utilisant l'ID unique de l'événement comme clé de déduplication.