technique · réponse sourcée
Webhook e-mail : définition et mise en œuvre technique
Un webhook e-mail est un callback HTTP déclenché par un fournisseur de services e-mail pour informer un serveur de destination de certains événements. Au lieu que l’application interroge régulièrement une API pour connaître les statuts, le fournisseur pousse une charge utile JSON ou XML vers une URL prédéfinie dès qu’un événement se produit, par exemple un échec de livraison ou un clic sur un lien.
Fonctionnement technique
Lorsqu’un événement se produit, le fournisseur d’e-mails génère une requête HTTP POST. Cette requête contient une charge utile avec les métadonnées de l’événement, notamment l’identifiant du message, l’adresse du destinataire et l’horodatage. Le serveur destinataire doit écouter sur un endpoint public, valider la requête entrante et renvoyer une réponse 200 OK pour en accuser réception. Si le serveur renvoie une erreur, le fournisseur peut retenter la livraison selon une stratégie de backoff exponentiel.
Pourquoi c’est important pour les expéditeurs
Les webhooks sont essentiels pour préserver la réputation d’expéditeur. En recevant en temps réel les notifications de hard bounces ou de plaintes pour spam, les développeurs peuvent retirer automatiquement les adresses invalides de leurs listes. Cela évite les envois répétés vers des boîtes aux lettres inactives, l’un des principaux signaux utilisés par les FAI pour classer un expéditeur comme de mauvaise qualité. Réagir rapidement à ces signaux garantit de meilleurs taux de délivrabilité globaux.
Considérations opérationnelles
Parmi les défaillances courantes figurent les erreurs de timeout lorsque le serveur destinataire traite la charge utile de manière synchrone. Pour les éviter, les développeurs doivent adopter une architecture asynchrone : le webhook est reçu, mis en file d’attente dans un système comme Redis ou RabbitMQ, puis acquitté immédiatement. La sécurité est par ailleurs primordiale : les serveurs doivent vérifier la signature du fournisseur ou contrôler l’IP source pour empêcher les notifications d’événements falsifiées.
Exemple concret de mise en œuvre
Un workflow typique consiste à configurer une URL chez un fournisseur comme Resend ou Amazon SES. Lorsqu’un utilisateur clique sur un lien dans un e-mail, le fournisseur envoie une requête POST à /webhooks/email avec un corps du type { event: click, email: user@example.com, link: https://site.com/offer }. L’application met ensuite à jour la fiche de l’utilisateur dans la base de données pour marquer la campagne comme réussie.
Intégration avec les outils
La mise en place de webhooks nécessite une URL publique et un moyen de tester les charges utiles. Les développeurs peuvent utiliser SendHQ ou ses outils gratuits (https://sendhq.cc/tools) pour gérer les exigences techniques de leur infrastructure e-mail et s’assurer que leur configuration respecte les normes du secteur.
Les questions que posent les équipes
Quelle est la différence entre une API et un webhook ?
Une API est une requête envoyée par le client au serveur pour récupérer des données. Un webhook est une requête envoyée par le serveur au client pour lui pousser automatiquement des données lorsqu’un événement se produit.
Comment sécuriser un endpoint de webhook e-mail ?
Utilisez des jetons secrets dans l’en-tête, vérifiez la signature HMAC fournie par le service e-mail ou limitez le trafic entrant aux plages d’IP appartenant au fournisseur.
Que se passe-t-il si mon serveur est indisponible lors d’un événement de webhook ?
La plupart des fournisseurs professionnels mettent l’événement en file d’attente et tentent de le livrer à nouveau plusieurs fois sur une période de plusieurs heures ou jours avant de le marquer comme non livrable.
Sources primaires
- Documentation Resend — Resend
- Documentation développeur Postmark — Postmark
- Guide du développeur Amazon SES — Amazon Web Services