Webhook

Definition

Un webhook est un mecanisme de notification HTTP ou un serveur envoie automatiquement une requete POST a une URL que vous avez configuree, quand un evenement specifique se produit. C'est le modele "push" par opposition au "pull" (polling) des API classiques.

Au lieu de demander regulierement "y a-t-il du nouveau ?", le webhook vous previent immediatement quand quelque chose se passe.

Comment ca fonctionne

1. Vous configurez une URL de webhook dans un service (Stripe, GitHub, Slack)
2. Un evenement se produit (paiement recu, push Git, message envoye)
3. Le service envoie un POST HTTP a votre URL avec les details de l'evenement
4. Votre serveur traite l'evenement 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. Verifier la signature

Chaque service signe ses webhooks avec un secret. Verifiez TOUJOURS la signature pour eviter les requetes falsifiees.

2. Repondre rapidement (< 5s)

Retournez 200 immediatement, puis traitez l'evenement en arriere-plan (queue, job async). Si votre endpoint met trop de temps, le service retentera.

3. Idempotence

Les webhooks peuvent etre envoyes plusieurs fois (retries). Votre code doit gerer 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 recu pour le debugging. Configurez des alertes si le taux d'erreur augmente.

Webhook vs Polling vs WebSocket