Webhooks SaaS : éviter les actions perdues ou exécutées deux fois

Pour fiabiliser la réception des webhooks dans une application web, l'architecture doit vérifier la signature cryptographique des appels, garantir l'idempotence des traitements et faire face à des livraisons dans un ordre aléatoire. La solution consiste à séparer la réception HTTP immédiate de l'exécution asynchrone des tâches métier. Chez Ikovaline, lors de prestations couvrant le développement de SaaS et d’applications web, cette approche garantit la cohérence des données même en cas de panne temporaire du réseau ou du serveur.

1. Vérification des signatures et validation de l'émetteur

Un webhook expose un point d'entrée HTTP public sur votre infrastructure. Sans contrôle strict, n'importe quel tiers pourrait envoyer de faux événements et altérer les données des utilisateurs. Pour sécuriser ces flux, la première étape impose de valider l'authenticité de l'expéditeur.

Selon la documentation officielle de Stripe sur les webhooks, la plateforme recommande formellement de vérifier la signature transmise dans l'en-tête de chaque requête. Le serveur récepteur utilise un secret de signature partagé pour recalculer l'empreinte et la comparer à celle envoyée. Si les empreintes ne correspondent pas ou si l'horodatage est trop ancien, la requête doit être rejetée immédiatement avec un code d'erreur.

Il convient de noter que toutes les API d'éditeurs tiers ne proposent pas les mêmes mécanismes de sécurité. Certaines plateformes utilisent une clé d'API statique dans l'en-tête, tandis que d'autres s'appuient sur des signatures asymétriques. L'équipe technique doit donc vérifier les spécifications de chaque fournisseur avant l'implémentation.

2. Gestion des doublons et principe d'idempotence

Les réseaux informatiques subissent parfois des latences ou des déconnexions. Lorsqu'un service externe ne reçoit pas de réponse d'acquittement dans le délai imparti, il réessaie d'envoyer la même notification. Comme le précise la documentation de Stripe, des livraisons en double sont possibles lors du fonctionnement normal du service.

Pour éviter de facturer deux fois un utilisateur ou de générer deux envois de commande, le traitement doit être idempotent. Cela signifie que l'exécution répétée du même message doit produire exactement le même résultat qu'une exécution unique.

Dans une architecture logicielle robuste, chaque événement est identifié par un identifiant unique fourni par l'émetteur. Avant d'exécuter l'action métier, le serveur vérifie si cet identifiant a déjà été enregistré dans la base de données. Si l'identifiant existe déjà, le système renvoie immédiatement une confirmation de réception sans réexécuter le traitement.

Cette approche implique de bien concevoir la persistance. Posséder l'intégralité de son code source ne supprime pas les frais d'infrastructure ni la maintenance applicative. Une attention particulière doit être portée à l'indexation de la table des événements enregistrés pour éviter que les vérifications d'idempotence ne ralentissent les requêtes.

3. Gestion du désordre dans l'arrivée des messages

Un autre défi réside dans la chronologie de réception des notifications. La documentation technique de Stripe rappelle expressément que l'ordre de livraison des événements n'est pas garanti. Un événement signifiant la résiliation d'un abonnement peut ainsi arriver avant l'événement annonçant sa création si les paquets empruntent des routes réseau différentes.

Pour traiter les données sans corruption, le logiciel ne doit pas s'appuyer uniquement sur l'ordre dans lequel les requêtes HTTP touchent le serveur. Plusieurs stratégies complémentaires sont recommandées :

• Comparer les horodatages internes : L'événement contient un champ indiquant le moment exact de sa création chez l'émetteur. Si la base de données contient déjà un état plus récent que l'événement reçu, la modification est ignorée.
• Interroger l'API en direct : Lors de la réception d'un événement critique, au lieu de faire confiance aveuglément au contenu du message, le système effectue un appel sortant vers l'API du fournisseur pour lire l'état en temps réel de la ressource.
• Stocker les événements dans une file d'attente : L'utilisation d'une file de messages permet de traiter les événements de manière ordonnée ou de suspendre temporairement les messages incohérents le temps que les dépendances soient résolues.

4. Recette et protocole de reprise sur incident

La fiabilisation des webhooks exige un protocole de test complet avant tout passage en production, suivi d'une procédure de reprise claire si un incident survient sur l'infrastructure.

En cas d'incident majeur sur les serveurs, certains webhooks peuvent échouer définitivement après l'épuisement des tentatives automatiques de l'émetteur. Il faut alors mettre en place un outil de relecture manuelle ou un script d'isolation des messages non traités. La structure du code doit séparer les fonctions d'ingestion de la logique d'exécution afin de rejouer des événements sauvegardés sans déclencher d'effets de bord secondaires.

Pour structurer vos projets applicatifs en respectant ces normes de qualité, vous pouvez consulter nos tarifs transparents ainsi que notre méthode de développement pas à pas. Vous pouvez également réserver un appel de cadrage offert de 45 minutes avec l'un de nos fondateurs.

Foire aux questions

Que faire si un webhook renvoie une erreur serveur ?

Lorsqu'un serveur renvoie un code d'erreur HTTP d'échec serveur, l'émetteur du webhook considère que la distribution a échoué. La plupart des fournisseurs sérieux effectuent des tentatives de livraison espacées dans le temps. Pour éviter de perdre des informations, votre infrastructure doit consigner l'erreur dans les journaux système et corriger rapidement la panne sous-jacente.

Pourquoi ne faut-il pas exécuter le traitement métier directement dans la route du webhook ?

Si le traitement métier comporte des opérations lentes, comme la génération d'un document ou l'envoi de plusieurs courriels, la connexion HTTP risque d'atteindre un délai d'expiration. L'émetteur pensera que le message n'a pas été distribué et le renverra. Répondre par un succès immédiatement après avoir placé l'événement dans une file de travail asynchrone évite ce problème.

Comment rejouer des événements manqués après une coupure de service ?

Après une interruption de service prolongée, il convient de consulter l'interface du fournisseur de services pour déclencher un rejeu manuel des événements manqués. Si le fournisseur ne propose pas cette option, l'application doit pouvoir interroger l'API du service pour synchroniser l'état de l'ensemble des objets modifiés durant la période d'indisponibilité.