Concevoir des webhooks e-mail pour une livraison « au moins une fois »

Le défi d’une livraison d’événements fiable

Pour obtenir une livraison at-least-once (au moins une fois) des webhooks e-mail, vous devez mettre en place un système où l’émetteur réessaie les requêtes en échec avec un backoff exponentiel et où le récepteur garantit l’idempotence. Les réseaux ne sont pas fiables et les serveurs tombent : vous ne pouvez pas supposer qu’un simple HTTP 200 OK garantit que l’événement a été traité. La fiabilité repose sur la combinaison d’une file de nouvelles tentatives persistante côté émetteur et d’une couche de déduplication côté récepteur.

Lorsque vous intégrez une API e-mail comme SendHQ, votre application doit savoir quand un e-mail a été délivré, a généré un bounce ou a été marqué comme spam. Ces événements sont asynchrones. Si votre endpoint de webhook tombe pendant cinq minutes lors d’un pic de trafic, vous pouvez perdre des milliers de signaux de livraison critiques. Cela crée un trou dans vos données analytiques et empêche votre système de réagir aux bounces (ce qui est essentiel pour préserver la réputation d’expéditeur).

Anatomie d’un webhook fiable

Une architecture de webhooks robuste repose sur trois piliers : la vérification de signature, le traitement idempotent et une stratégie de nouvelles tentatives.

1. Vérification de signature

Ne faites jamais confiance à une requête POST vers votre endpoint de webhook sur la seule base de l’adresse IP ou de la présence d’une clé API dans le corps. Un attaquant peut les usurper. Utilisez plutôt une signature HMAC (Hash-based Message Authentication Code).

L’émetteur signe le payload avec un secret partagé et joint la signature dans un en-tête (par exemple X-SendHQ-Signature). Le récepteur recalcule le hash avec le même secret et le compare à l’en-tête.

const crypto = require('crypto'); function verifySignature(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); // Use timingSafeEqual to prevent timing attacks return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature)); }

2. Idempotence et déduplication

Une livraison at-least-once signifie que l’émetteur continuera d’envoyer l’événement jusqu’à recevoir une réponse de succès. Si votre serveur traite l’événement mais plante avant d’envoyer le 200 OK, l’émetteur renverra l’événement. Sans idempotence, vous risquez de compter une seule livraison comme deux dans votre base de données.

Chaque événement doit avoir un event_id unique. Utilisez un mécanisme de clé d’idempotence pour suivre les événements déjà traités.

Le workflow :

1. Recevez le payload du webhook.
2. Vérifiez si l’event_id existe dans votre table processed_events.
3. S’il existe, renvoyez immédiatement 200 OK et ignorez le corps.
4. S’il n’existe pas, traitez l’événement et enregistrez l’event_id dans une seule et même transaction.

3. La stratégie de nouvelles tentatives

Du point de vue de l’émetteur, une politique de nouvelles tentatives est indispensable. Le schéma classique est un backoff exponentiel avec jitter. Par exemple : nouvelle tentative après 1 minute, 5 minutes, 30 minutes, 2 heures et 12 heures.

Si le récepteur renvoie une erreur 4xx (sauf 429), cela indique généralement une erreur côté client (comme une signature invalide), et réessayer ne servira à rien. Une erreur 5xx ou un timeout indique un échec transitoire, pour lequel les nouvelles tentatives sont indispensables.

Exemple concret de payload

Voici un payload typique d’événement de livraison que vous pourriez recevoir de SendHQ :

{ "event_id": "evt_12345abcde", "event_type": "delivered", "timestamp": "2026-09-15T10:00:00Z", "message_id": "msg_98765xyz", "recipient": "user@example.com", "metadata": { "order_id": "ord_5544" } }

Gérer les échecs et les cas limites

Le problème du « consommateur lent »

Si votre gestionnaire de webhooks effectue de lourdes écritures en base ou appelle d’autres API externes de manière synchrone, votre endpoint finira en timeout. Cela déclenche la logique de nouvelles tentatives de l’émetteur et provoque une « tempête de retries » qui peut faire tomber votre serveur.

La solution : découplez la réception du traitement.

1. Recevez le webhook.
2. Vérifiez la signature.
3. Poussez le payload brut dans une file de messages (comme RabbitMQ, SQS ou Redis).
4. Renvoyez immédiatement 200 OK.
5. Un processus worker distinct consomme la file et met à jour votre base de données.

Le problème de la préparation des agents

Lorsque des agents IA sont déclenchés par des webhooks, le risque de boucles infinies augmente. Si un agent reçoit un événement « delivered » et y répond en envoyant un autre e-mail, qui déclenche à son tour un nouvel événement « delivered », vous avez une boucle.

Considérez l’envoi d’un e-mail comme un effet de bord externe. Les agents ne doivent jamais envoyer d’e-mails automatiquement à partir d’un webhook sans validation humaine dans la boucle ou sans contrôle strict par machine à états garantissant que l’action est nécessaire.

Comparer l’écosystème

Lorsque vous choisissez un fournisseur, la fiabilité dépend souvent de la façon dont il gère ces événements et de ce qu’il facture pour le volume d’e-mails qui les génère.

Pour les e-mails transactionnels à fort volume, l’écart de coût est frappant. Selon la tarification d’Amazon SES, l’envoi à la carte coûte 0.10 USD pour 1 000 e-mails. À l’inverse, la tarification de Postmark commence à 15 USD par mois pour 10 000 e-mails, avec des dépassements entre 1.20 et 1.80 USD pour 1 000. Pour un volume de 50 000 e-mails, SES à la carte coûte environ 5 USD, contre environ 66 USD avec les paliers de Postmark.

Parmi les autres options, Resend propose une offre gratuite de 3 000 e-mails par mois (plafonnée à 100 par jour) et une formule Pro à 20 USD par mois pour 50 000 e-mails. Mailgun démarre à 15 USD par mois pour 10 000 e-mails. SendGrid a transformé son offre gratuite en essai de 60 jours, avec Essentials à partir de 19.95 USD par mois.

Quel que soit le fournisseur, c’est la fiabilité de votre consommation de ces événements qui détermine l’intégrité de vos données.

Checklist d’implémentation pour les ingénieurs

• Vérification de signature : le payload est-il vérifié au moyen d’un secret partagé et d’une fonction de comparaison à temps constant ?
• Traitement asynchrone : l’endpoint renvoie-t-il 200 OK avant d’exécuter une logique métier lourde ?
• Idempotence : existe-t-il une contrainte d’unicité sur event_id pour empêcher le traitement en double ?
• Gestion des timeouts : le timeout est-il défini à une valeur inférieure au timeout du fournisseur afin d’éviter les nouvelles tentatives qui se chevauchent ?
• Surveillance : disposez-vous d’alertes pour un pic de réponses 5xx sur votre endpoint de webhook ?
• État du DNS : vos serveurs de réception sont-ils correctement configurés ? Utilisez des outils comme le vérificateur DNS e-mail de SendHQ pour vous assurer que votre infrastructure est accessible et correctement configurée.
• Normes d’authentification : avez-vous implémenté DKIM, SPF et DMARC pour que vos e-mails sortants soient acceptés, ce qui réduit le nombre de webhooks de "bounce" à traiter ?

Synthèse des compromis

Approche | Avantages | Inconvénients

Traitement synchrone | Simple à implémenter, cohérence immédiate | Risque élevé de timeouts, sujet aux tempêtes de retries

Traitement par file | Très scalable, résistant aux pics | Infrastructure plus complexe, cohérence à terme

Simple journalisation | Faible surcoût | Aucun moyen de récupérer les événements manqués sans logs manuels

Table d’idempotence | Intégrité des données garantie | Une écriture en base supplémentaire par événement

Conclusion

La fiabilité des webhooks e-mail ne consiste pas à empêcher les échecs, mais à concevoir en les anticipant. En partant du principe que le réseau tombera en panne et que les événements seront livrés plus d’une fois, vous construisez un système réellement résilient. Que vous gériez les enregistrements SPF d’un petit projet ou que vous fassiez évoluer un système transactionnel massif, la vérification de signature et l’idempotence restent la référence.

Construisez votre infrastructure e-mail avec SendHQ.