Définir l’événement séparément de sa livraison
Précisez le sens de chaque événement, son moment de création et la ressource décrite. Attribuez un identifiant durable qui reste identique lors d’une nouvelle tentative. Distinguez-le d’une requête HTTP ou d’une tentative individuelle. Ajoutez une version de schéma et assez de contexte pour retrouver l’enregistrement faisant autorité. Évitez de demander au consommateur d’inférer un changement métier à partir d’un vague « quelque chose a changé ». Des exemples doivent expliquer champs facultatifs, valeurs omises et modifications. Convenez si le message contient un état complet ou invite à récupérer l’état courant.
Prévoir les doublons et l’ordre des messages
Partez du principe qu’un envoi peut être répété ou arriver après un message plus récent. Le destinataire doit mémoriser les événements traités et rendre leur effet métier répétable sans conséquence supplémentaire. Recevoir deux fois la même notification ne doit pas créer deux droits d’accès ou deux dossiers de support, sauf intention explicite. Pour les changements séquentiels, définissez une référence d’ordre ou une comparaison à l’état courant. L’heure d’arrivée ne remplace pas implicitement l’ordre métier. Testez un ensemble volontairement mélangé et décrivez le résultat avant de choisir l’implémentation. Les deux équipes doivent savoir quel système arbitre les conflits.
Rendre les échecs visibles sans répétition infinie
Définissez la livraison acceptée et distinguez incidents temporaires et demandes nécessitant une correction. Prévoyez des tentatives limitées et visibles, puis un état permettant d’examiner les événements non résolus. L’opérateur a besoin de l’identifiant, de la destination, du dernier essai, du type de réponse et de la prochaine action. Protégez les champs sensibles dans les journaux et interfaces. Un délai dépassé peut laisser l’émetteur incertain malgré un traitement achevé chez le destinataire ; l’enquête doit utiliser les identifiants durables des deux côtés. Un bouton de reprise doit expliquer l’opération répétée et conserver l’identité d’origine.
Fournir un guide opérationnel aux responsables
Documentez configuration, vérification du point de réception, rotation des secrets, événements de test et pause temporaire. Désignez le responsable de l’endpoint et la procédure de revue des changements. Permettez d’examiner un exemple sans exposer les secrets de production et identifiez clairement les environnements. Lors de la réception, simulez un destinataire indisponible, un message invalide, un doublon et la reprise après correction. Vérifiez les données résultantes du client autant que l’écran d’envoi. Le livrable utile est une connexion fiable au comportement explicable, et non un badge vert obtenu sur une seule requête de démonstration.