Webhooks

Vous devez lancer une automatisation dès qu’un paiement, un formulaire ou une modification arrive. Interroger l’API toutes les minutes gaspille des appels et ajoute un délai. Un webhook permet au système source de prévenir votre application au moment de l’événement.

Un webhook est une livraison HTTP envoyée par un fournisseur vers une URL que vous avez enregistrée. Vous choisissez les événements utiles. Lorsqu’un de ces événements survient, le fournisseur envoie une requête contenant son type et ses données. [S1]

Le webhook transporte une notification. Il ne garantit pas que votre traitement métier a réussi, que la livraison n’arrivera qu’une fois ou qu’un autre événement ne la dépassera pas. [S2] [S4]

Choisir entre webhook et vérification périodique

Besoin	Mécanisme de départ
Réagir rapidement à des événements pris en charge par le fournisseur	Webhook
Lire une information une seule fois ou à la demande	Appel API direct
Vérifier un petit nombre de ressources à faible fréquence	Vérification périodique possible
Reconstituer un état complet ou rattraper une période manquante	API de lecture ou export, même si un webhook existe
Le fournisseur ne garantit ni la livraison, ni sa reprise	Vérification périodique ou mécanisme hybride

Les webhooks évitent des appels répétés, approchent le temps réel et s’adaptent mieux à un grand nombre de ressources. Une lecture ponctuelle ou rare reste plus simple avec l’API. [S1]

Dans une intégration importante, combinez souvent les deux mécanismes : le webhook déclenche le travail et l’API permet de relire l’état canonique, de compléter des données ou de rattraper une livraison manquée.

Le contrat à obtenir du fournisseur

Avant d’implémenter le récepteur, documentez :

• les types d’événements et leurs versions ;
• le mécanisme d’authenticité et le format exact des données qu’il protège ;
• l’identifiant stable de l’événement ou de la livraison ;
• le délai maximal avant accusé de réception ;
• les codes HTTP considérés comme un succès ;
• la politique de nouvelle livraison et sa durée ;
• la garantie, ou l’absence de garantie, sur l’ordre ;
• la méthode de récupération d’un objet ou d’un événement manquant ;
• les limites de taille, de débit et de conservation.

Ces valeurs dépendent du fournisseur. Par exemple, GitHub attend une réponse 2xx en moins de dix secondes et recommande d’utiliser l’identifiant X-GitHub-Delivery. Stripe demande une réponse 2xx rapide, peut réessayer un événement et ne garantit pas l’ordre de livraison. [S2] [S4]

Traiter une livraison dans le bon ordre

1. Conserver le corps brut lorsque la vérification l’exige. GitHub et Stripe calculent leur signature à partir du contenu reçu. Une transformation préalable peut invalider le calcul. [S3] [S4]
2. Vérifier l’authenticité selon le contrat. Appliquez le mécanisme documenté par le fournisseur avant tout traitement. GitHub et Stripe utilisent une signature calculée avec le secret partagé de l’endpoint. Dans ce cas, calculez la signature sur le corps brut et comparez-la en temps constant. [S3] [S4]
3. Contrôler la fraîcheur si elle est signée. Un horodatage signé permet de refuser une ancienne requête rejouée. Stripe inclut cet horodatage dans sa signature. [S4]
4. Identifier le type et l’action. Ignorez proprement les événements non pris en charge. Un fournisseur peut ajouter de nouveaux types ou actions. [S2]
5. Prendre en charge atomiquement. Utilisez l’identifiant stable comme clé unique. Pour une nouvelle livraison, créez dans une même transaction l’état pris en charge et le travail durable à exécuter. Si la file ne partage pas ce stockage, écrivez plutôt une entrée durable de type outbox dans la transaction, puis republiez-la jusqu’à son acceptation par la file. Un identifiant déjà traité désigne un doublon résolu. Un identifiant pris en charge signale une exécution en cours : vérifiez que son travail reste durable ou réparez sa mise en attente avant de poursuivre.
6. Répondre seulement après une prise en charge durable. Retournez le succès attendu lorsque la livraison est valide et que son identifiant est déjà traité, ou lorsque son travail est pris en charge dans un mécanisme récupérable. Si la file est indisponible et qu’aucune entrée durable ne peut être créée, ne marquez pas la livraison comme traitée. Retournez la réponse d’échec prévue par le contrat afin que sa politique de reprise puisse s’appliquer.
7. Traiter de façon idempotente. Une nouvelle livraison du même événement ne doit pas répéter un paiement, un envoi ou une création. Passez à l’état traité seulement après avoir enregistré le résultat final.
8. Journaliser le résultat. Conservez l’identifiant, le type, l’heure, le statut et l’erreur utile, sans stocker plus de données sensibles que nécessaire.

HTTPS protège le transport. Il ne prouve pas que la requête vient du fournisseur. La signature du corps et l’identifiant de livraison répondent à des risques différents : falsification, altération, rejeu et doublon. [S2] [S3] [S4]

Gérer les reprises et l’ordre variable

Une absence de réponse ou un code d’erreur peut déclencher une nouvelle livraison. Le récepteur doit donc supposer qu’un même événement peut arriver plusieurs fois. L’identifiant de l’événement sert à reconnaître ce doublon. Le traitement métier doit aussi être idempotent lorsque plusieurs événements distincts décrivent le même effet. [S2] [S4]

Ne déduisez pas l’état courant de l’ordre d’arrivée. Stripe indique que des événements liés peuvent être livrés dans un ordre différent de leur création. Si une décision dépend de l’état actuel, relisez l’objet canonique avec l’API du fournisseur et utilisez l’événement comme déclencheur. [S4]

Prévoyez également un rattrapage : liste des livraisons en échec, commande de nouvelle livraison, lecture des événements depuis un curseur ou vérification périodique limitée. GitHub recommande de redélivrer les événements manqués après une indisponibilité. [S2]

Tester avant la mise en service

Vérifiez au minimum :

• lorsque le fournisseur utilise une signature, une signature valide, absente, altérée et calculée sur un corps modifié ;
• un événement connu et un type inconnu ;
• deux livraisons portant le même identifiant ;
• deux événements liés reçus dans l’ordre inverse ;
• une file indisponible avant l’accusé de réception ;
• une erreur métier après une réponse 2xx ;
• une nouvelle livraison après délai ;
• une montée en charge supérieure au rythme de traitement ;
• lorsque ce secret existe, une rotation du secret de signature ;
• un rattrapage après une interruption prolongée.

Mesurez le délai d’accusé de réception, le nombre de signatures invalides, les doublons évités, les événements en attente, les échecs de traitement et l’âge de la plus ancienne livraison non résolue.

Limites à garder visibles

• Un 2xx confirme la réception selon le contrat du fournisseur, pas la réussite finale du métier.
• Lorsqu’une signature est utilisée, sa validité confirme l’origine et l’intégrité selon la clé utilisée, pas la vérité de toutes les données.
• Un webhook peut être perdu si aucune nouvelle livraison ni lecture de rattrapage n’existe.
• Lorsqu’un secret de signature est utilisé, son exposition permet de fabriquer des requêtes valides. Il doit être stocké et renouvelé comme un secret.
• Un payload peut contenir des données personnelles ou confidentielles qui ne doivent pas être copiées dans tous les journaux.
• Une dépendance à l’ordre d’arrivée rend le traitement fragile.

Utilisez un webhook pour recevoir rapidement un changement, puis traitez chaque livraison comme un message susceptible d’être répété, retardé ou désordonné. Vérifiez son authenticité selon le contrat du fournisseur, enregistrez son identité, répondez vite et gardez un chemin de rattrapage vers la source canonique.