Les webhooks sont géniaux, jusqu’à ce que votre serveur de destination tombe en panne ou que la connexion réseau soit interrompue. Les webhooks fonctionnent par nature selon le principe “envoyer et oublier” (fire and forget), mais dans les processus commerciaux critiques (comme la réception de paiements), “oublier” n’est pas une option.

Dans cet article, nous examinerons comment vous pouvez rendre votre architecture de webhook plus résiliente et comment réduire la perte de données à 0%.

1. Gestion des délais d’attente (Timeout)

Le service envoyant le webhook n’attend pas une réponse éternellement. Il y a généralement un délai d’attente de 5 à 10 secondes. Si votre endpoint ne répond pas dans ce délai, la requête est considérée comme échouée.

Solution : N’effectuez jamais d’opérations de longue durée (création de PDF, envoi d’e-mails, rapports de base de données) sur l’endpoint qui reçoit le webhook. La seule chose que vous devez faire est :

Recevoir la requête.
La mettre en file d’attente (Queue).
Renvoyer 200 OK à l’expéditeur.
Effectuer l’opération en arrière-plan (Background Worker).

2. Mécanisme de nouvelle tentative (Retry)

Chaque système peut tomber en panne. Votre serveur peut être en maintenance ou il peut y avoir une erreur réseau instantanée. Dans ces cas, le webhook ne doit pas être perdu.

Exponential Backoff : Au lieu de réessayer immédiatement une requête échouée, la méthode la plus saine est d’essayer en augmentant le temps d’attente.

1ère tentative : Erreur
2ème tentative : Après 5 secondes
3ème tentative : Après 30 secondes
4ème tentative : Après 5 minutes

Examinez impérativement la politique de nouvelle tentative de votre fournisseur de webhook (par exemple, Stripe). Mettez également en place une stratégie de nouvelle tentative dans vos propres soumissions de webhook.

3. Idempotence

Le mécanisme de nouvelle tentative est génial mais a un effet secondaire dangereux : La même requête arrive plus d’une fois. Si la réponse 200 OK n’atteint pas l’expéditeur en raison d’une erreur réseau, l’expéditeur envoie à nouveau le même webhook. Si votre code n’est pas préparé à cela, vous pourriez facturer le client deux fois ou créer des enregistrements en double dans la base de données.

Solution : Il y a un ID unique (Event ID) dans chaque requête webhook. Conservez cet ID dans votre base de données ou Redis.

if redis.exists(event_id) {
    return 200 OK; // Déjà traité, ne pas refaire.
}
process_payment();
redis.save(event_id);

4. Sécurité et Vérification (HMAC)

Puisque votre endpoint est public, des personnes malveillantes peuvent envoyer de fausses requêtes webhook. Pour éviter cela, il est obligatoire de vérifier la signature HMAC (Hash-based Message Authentication Code). L’expéditeur hache la payload avec une clé secrète et l’envoie dans l’en-tête. Vous effectuez la même opération et vérifiez si elle correspond.

5. Dead Letter Queue (DLQ)

Que se passe-t-il si toutes les tentatives de nouvelle tentative échouent ? Au lieu de supprimer les données, déplacez-les vers une zone distincte appelée “Dead Letter Queue”. Vous pouvez examiner manuellement les enregistrements erronés ici plus tard et les traiter à nouveau après avoir résolu le problème.

Résumé

Construire une architecture de webhook fiable nécessite une gestion des files d’attente, des stratégies de nouvelle tentative et des mesures de sécurité.

Si vous ne voulez pas construire toute cette infrastructure (Queue, Retry, DLQ, Logging) à partir de zéro, vous pouvez utiliser une passerelle Webhook comme WebhookIO. WebhookIO reçoit toutes les requêtes entrantes pour vous, les met en file d’attente et vous les livre en toute sécurité lorsque votre endpoint est prêt.

Mesures critiques pour éviter de perdre des requêtes Webhook