API email et webhooks : éviter les doublons avec l’idempotence

Une intégration email doit savoir reprendre une action sans créer involontairement un nouvel envoi. C’est le rôle de l’idempotence, complétée par un suivi durable des opérations. Les webhooks demandent un second contrôle : recevoir plusieurs fois une notification ne doit pas répéter son effet.

Ce guide s’adresse aux responsables de sites, aux équipes produit et aux prestataires qui les accompagnent. Il propose une architecture de travail à adapter au fournisseur utilisé ; il ne décrit pas une fonction actuellement disponible dans une plateforme particulière.

Comprendre le risque d’une réponse perdue

Imaginez qu’un site demande l’envoi d’une confirmation. Le service accepte, mais la réponse se perd avant de revenir au site. Celui-ci sait qu’il n’a pas reçu de confirmation technique ; il ne sait pas nécessairement si l’action a été exécutée.

Relancer avec une nouvelle demande peut alors créer une seconde copie. La RFC 9110 définit l’idempotence comme la conservation du même effet voulu lorsque des requêtes identiques se répètent, et encadre les reprises de méthodes non idempotentes.

Pour l’équipe métier, la question devient simple : comment l’application reconnaît-elle qu’elle tente la même action ? Un bouton grisé dans l’interface ne répond pas à tous les cas, notamment aux reprises automatiques côté serveur.

Donner une identité stable à l’action d’envoi

Nous proposons de créer une référence interne avant l’appel au prestataire. Elle représente l’action métier : envoyer la confirmation d’une réservation précise, dans une version déterminée.

Cette référence doit rester la même lorsque vous reprenez cette action après un incident. En générer une nouvelle à chaque tentative annulerait le mécanisme recherché. Évitez également d’utiliser l’adresse email seule : plusieurs messages légitimes peuvent être destinés à la même personne.

Conservez la référence avec le contenu prévu ou son empreinte, l’état de traitement et l’identifiant retourné par le fournisseur. Ne placez pas de données personnelles inutiles dans une clé qui pourrait être visible dans des journaux techniques.

Vérifier le contrat de l’API

Certaines API fournissent une clé d’idempotence explicite. Resend, par exemple, documente cette fonction avec une fenêtre de conservation de 24 heures et des règles pour les requêtes dont le contenu diffère.

Ces conditions sont propres au fournisseur. Vérifiez les points de terminaison couverts, la durée, le comportement en concurrence et les réponses d’erreur. Ne transposez pas une règle d’un service à un autre.

Votre application doit aussi prévoir une reprise après expiration de cette fenêtre. Si l’état initial reste inconnu, une nouvelle tentative automatique ne doit pas être considérée comme sûre par défaut. Préparez une recherche dans les éléments du fournisseur ou une procédure de résolution manuelle.

Conserver un état avant et après l’appel

Un modèle de travail peut distinguer une action prévue, en cours, acceptée par le fournisseur, en échec certain ou à vérifier. Ces états sont proposés pour clarifier l’exploitation ; ils ne constituent pas une nomenclature universelle.

Enregistrez l’intention d’envoi durablement avant de lancer l’appel. Associez les reprises à la même opération. Si deux traitements concurrents essaient de travailler sur cette opération, une contrainte d’unicité ou un mécanisme de coordination doit empêcher la création de deux intentions indépendantes.

N’assimilez pas « accepté par l’API » à « lu par le destinataire ». Votre suivi doit conserver le sens exact de chaque étape. Donnez à l’équipe de support un vocabulaire commun pour éviter qu’elle confonde une nouvelle tentative avec une nouvelle demande métier autorisée.

Traiter les webhooks comme une autre chaîne

Un webhook transmet un événement à votre application. Le fournisseur peut le renvoyer après un échec de réception ; Resend décrit notamment ses reprises et rejeux.

Utilisez l’identifiant unique de l’événement prévu par le fournisseur, avec son origine. Ne confondez pas cet identifiant avec celui du message : un même email peut donner lieu à plusieurs événements légitimes.

Le traitement doit supporter une notification déjà reçue. Si un événement signifie qu’une adresse doit être exclue d’un prochain envoi, une nouvelle livraison du même événement ne doit pas recréer des opérations métier inutiles.

Vérifier, enregistrer et acquitter au bon moment

Vérifiez d’abord l’authenticité de la requête avec la méthode documentée. La documentation Resend rappelle notamment l’importance du corps brut pour la vérification de signature.

Nous proposons ensuite d’enregistrer durablement l’événement et le travail à effectuer avant de confirmer sa réception. Un traitement différé peut appliquer l’effet métier, puis marquer l’opération comme terminée dans la même transaction lorsque les données partagent une base.

Une entrée « déjà vue » ne doit pas signifier « travail terminé » si une panne s’est produite entre les deux. Si l’effet appelle un autre service, cette sortie a besoin de son propre mécanisme de reprise et d’idempotence. La frontière entre systèmes doit rester visible.

Exemple fictif : une inscription à un atelier

Imaginons un site de réservation. Une personne valide son inscription ; le serveur crée une opération « confirmation de réservation » et appelle le service email. La réponse est perdue.

Le serveur reprend l’opération avec la même clé et le même contenu, selon le contrat de l’API. Plus tard, la notification de livraison arrive deux fois. L’application conserve un seul traitement métier pour cet événement, grâce à son identifiant.

Ce scénario fictif distingue bien les deux problèmes : dédupliquer la demande d’envoi et dédupliquer l’effet d’une notification. Résoudre seulement le second n’empêcherait pas une application de demander deux emails.

Tester les pannes qui comptent

Avant la mise en service, demandez des essais sur les situations suivantes :

• Même action déclenchée plusieurs fois, y compris simultanément.
• Réponse API perdue après une acceptation.
• Même clé réutilisée avec un contenu différent.
• Notification reçue plusieurs fois ou après une panne.
• Arrêt entre l’enregistrement et l’application de l’effet métier.
• Reprise tardive au-delà des garanties du fournisseur.

Le résultat attendu doit être explicite pour chaque essai : opération unique, état à vérifier, reprise possible ou intervention humaine. Un test limité au parcours où tout répond immédiatement laisse les questions essentielles ouvertes.

Ajoutez un cas de désinscription survenue avant une reprise différée. L’autorisation et la pertinence d’un envoi doivent être réévaluées au moment approprié ; l’idempotence ne constitue pas une permission de continuer à envoyer.

Prévoir un journal compréhensible pour le support

Conservez les identifiants utiles, les états, les heures et les décisions de reprise, avec une durée adaptée au besoin. Une personne de support doit pouvoir distinguer un doublon visuel d’un nouvel envoi réellement demandé.

Évitez une promesse absolue de livraison « exactement une fois » à travers tous les systèmes. Décrivez plutôt les garanties réelles, leurs limites et la manière de résoudre les états incertains.

Vous obtenez une intégration exploitable : les reprises sont prévues, les effets sont contrôlés et une panne ne pousse pas l’équipe à renvoyer à l’aveugle.