GuidesIntégrations

Webhook : le principe, et comment le recevoir sans erreur

Par l’équipe Banzai LabsMis à jour le 2 min de lecture

Service Apayment.paidPOST{ JSON }SignéVotre app200 OKSinon, il réessaieIl vous prévient, vous n’avez pas à demander
Un webhook : le service vous envoie l’événement dès qu’il arrive, signé, et réessaie en cas d’échec.

Le principe

Stripe, Shopify, GitHub ou un service de signature électronique envoient un POST en JSON à l’adresse que vous leur donnez, à chaque événement : payment.paid, order.created.

Les quatre règles de réception

  1. 1Vérifier la signatureLe service signe chaque message avec un secret partagé. Sans signature valide, on rejette.
  2. 2Répondre viteUn 200 tout de suite, le traitement ensuite, dans une file.
  3. 3Tolérer les doublonsOn garde l’identifiant de chaque événement traité.
  4. 4Tout journaliserPour rejouer un événement ou comprendre une erreur.

Les erreurs fréquentes

Erreur Conséquence
Pas de vérification de signature N’importe qui peut simuler un paiement
Traitement long avant de répondre Le service croit à un échec et renvoie
Pas de contrôle des doublons Une commande expédiée deux fois
Ordre supposé des événements Un statut ancien écrase le récent

Pour les automatisations, voir n8n, Make ou sur mesure et Codes HTTP.

Questions fréquentes

Webhook ou API ?
Avec une API, vous demandez « du nouveau ? » à intervalles. Avec un webhook, le service vous appelle quand il y a du nouveau. Moins d’appels, moins de délai.
Que se passe-t-il si mon serveur est en panne ?
La plupart des services réessaient pendant un certain temps. Prévoyez aussi une resynchronisation par l’API pour rattraper un événement perdu.
Pourquoi recevoir deux fois le même événement ?
Parce que le service réessaie quand il n’a pas eu de réponse à temps. Votre code doit reconnaître un événement déjà traité et l’ignorer.

À lire ensuite

Tous les guides