Un webhook fiable traite chaque événement avec une vérification d’origine, une réponse rapide et une reprise prévue lorsque le traitement échoue.
Un webhook permet à un service partenaire de prévenir votre logiciel qu’un paiement, une commande ou un dossier a changé. L’appel arrive parfois plusieurs fois, dans le désordre ou après un délai. Le récepteur doit donc distinguer la réception technique du traitement métier.
Commencez par documenter les événements attendus. Pour chacun, indiquez son identifiant, sa version, sa ressource, sa date d’émission et les actions possibles. Le consommateur doit savoir si l’événement représente un état final ou une notification qui exige une nouvelle lecture auprès du service source.
Vérifier la provenance de la requête
Le récepteur doit vérifier la signature ou le mécanisme d’authentification prévu par le partenaire. Conservez le secret dans un stockage protégé et prévoyez sa rotation. Comparez les signatures sans exposer le contenu dans les messages d’erreur.
Une protection contre la répétition peut inclure un horodatage dans la signature. Refusez les messages trop anciens selon une fenêtre adaptée, tout en prévoyant un mécanisme de rejeu administré pour les incidents. L’horodatage du partenaire ne doit pas remplacer la vérification de l’identifiant de l’événement.
Les adresses IP autorisées peuvent compléter la signature, mais elles ne doivent pas être l’unique contrôle si le fournisseur utilise un réseau variable. Documentez les changements de configuration et testez les règles avant une rotation.
Répondre rapidement puis traiter
Le endpoint doit vérifier le format minimal, enregistrer l’événement et répondre dans le délai annoncé par le partenaire. Le traitement lourd peut être placé dans une file. Un appel réseau ou une opération de génération de document ne doit pas bloquer la réponse pendant plusieurs secondes sans raison.
Une réponse de succès signifie que le système a accepté l’événement, pas forcément que toutes les actions secondaires sont terminées. Le contrat doit expliquer la différence. Si l’événement ne peut pas être enregistré, retournez une erreur qui provoquera une nouvelle tentative selon la règle du partenaire.
Ne retournez pas un succès pour cacher un problème permanent. Vous pourriez perdre l’événement si le fournisseur considère la livraison réussie. En revanche, une erreur temporaire doit être signalée sans transformer une panne courte en avalanche de reprises.
Rendre le traitement idempotent
Le même événement peut être envoyé plusieurs fois après un délai réseau. Enregistrez son identifiant et le type de traitement avant d’appliquer les effets de bord. Une contrainte d’unicité ou une opération équivalente évite de créer deux commandes ou deux notifications.
Un doublon déjà traité doit recevoir une réponse cohérente. Le système peut retourner un succès en indiquant que l’événement était connu, sans déclencher une seconde action. Un événement reçu pendant qu’un premier traitement est encore en cours doit attendre ou être traité selon un état réservé.
L’idempotence doit couvrir les actions secondaires. Marquer la commande comme payée une seule fois ne suffit pas si le code envoie une notification deux fois. Chaque effet qui peut être répété mérite une clé métier ou une vérification adaptée, comme le décrit la gestion des doublons dans une intégration CRM et ERP.
Gérer l’ordre et les versions
Deux événements peuvent arriver dans un ordre différent. Le système doit comparer leur version ou leur date métier lorsqu’une ancienne information ne doit pas remplacer une nouvelle. Si le partenaire ne fournit pas de séquence, rechargez l’état courant avant une modification sensible.
Un changement de schéma doit être annoncé. Acceptez temporairement la version précédente lorsque c’est possible et refusez clairement une version inconnue. Ne supprimez pas immédiatement un champ sans vérifier les messages qui circulent encore dans les files.
Conservez le contenu nécessaire au diagnostic selon la politique de données. Une copie complète peut contenir des informations sensibles. Stockez plutôt les métadonnées et les champs indispensables, avec un accès limité au support.
Prévoir les échecs et les reprises
Une file de traitement doit distinguer les erreurs temporaires des événements invalides. Les premiers peuvent être retentés avec un délai croissant et une limite. Les seconds vont dans une file de quarantaine avec une raison lisible et une procédure de correction.
Une reprise manuelle doit utiliser le même mécanisme d’idempotence. L’administrateur doit voir l’identifiant de l’événement, son état, ses tentatives et l’action qu’il demande. Toute relance doit apparaître dans le journal d’audit.
Surveillez le temps entre réception et traitement, l’âge de la file, le nombre de doublons et les erreurs de signature. Une hausse des doublons peut indiquer une réponse trop lente, tandis qu’une hausse des signatures invalides peut signaler une mauvaise rotation ou une tentative non autorisée.
Tester avec le partenaire
Utilisez un environnement de test et des événements réels anonymisés. Vérifiez les doublons, l’ordre inversé, les champs absents, la signature invalide, les reprises et la rotation du secret. Testez aussi un arrêt du consommateur pendant que le fournisseur continue ses tentatives.
Les résultats de test doivent préciser le délai de réponse, le code retourné et l’état final dans le logiciel. Une spécification d’API partenaire peut consigner ces contrats et leurs versions.
Un webhook bien conçu reste simple à recevoir, mais explicite sur la sécurité, la répétition et l’échec. Ces règles permettent au logiciel de continuer à traiter les événements lorsque le réseau ou le partenaire ne suit pas le scénario idéal.
Sources : Stripe, bonnes pratiques des webhooks, OWASP, vérification des signatures.