Webhook

Définition

Un webhook est un mécanisme de notification HTTP ou un serveur envoie automatiquement une requête POST à une URL que vous avez configurée, quand un événement spécifique se produit. C'est le modèle "push" par opposition au "pull" (polling) des API classiques.

Au lieu de demander régulièrement "y a-t-il du nouveau ?", le webhook vous previent immédiatement quand quelque chose se passe.

Comment ca fonctionne

1. Vous configurez une URL de webhook dans un service (Stripe, GitHub, Slack)
2. Un événement se produit (paiement reçu, push Git, message envoye)
3. Le service envoie un POST HTTP à votre URL avec les détails de l'événement
4. Votre serveur traite l'événement et retourne un 200 OK

Exemple : webhook Stripe

// endpoint /api/webhooks/stripe
app.post('/api/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);

  switch (event.type) {
    case 'payment_intent.succeeded':
      await confirmOrder(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await cancelSubscription(event.data.object);
      break;
  }

  res.status(200).json({ received: true });
});

Bonnes pratiques essentielles

1. Vérifier la signature

Chaque service signe ses webhooks avec un secret. Vérifiez TOUJOURS la signature pour éviter les requêtes falsifiees.

2. Répondre rapidement (< 5s)

Retournez 200 immédiatement, puis traitez l'événement en arriere-plan (queue, job async). Si votre endpoint met trop de temps, le service retentera.

3. Idempotence

Les webhooks peuvent être envoyes plusieurs fois (retries). Votre code doit gérer les doublons :

// Verifier si l'evenement a deja ete traite
const exists = await db.query('SELECT 1 FROM processed_events WHERE event_id = $1', [event.id]);
if (exists) return res.status(200).send('Already processed');

4. Logging et monitoring

Loguez chaque webhook reçu pour le debugging. Configurez des alertes si le taux d'erreur augmente.

Webhook vs Polling vs WebSocket