Distinguer réception et traitement terminé
Les garanties dépendent du fournisseur. Stripe documente notamment les doublons possibles et l’absence d’ordre garanti. Une réponse HTTP de succès doit correspondre à une réception durable ou au traitement prévu, pas simplement à l’arrivée d’une requête en mémoire.
| Situation | Comportement attendu | Preuve utile |
|---|---|---|
| Même événement reçu deux fois | Éviter le double effet métier. | Identifiant traité et résultat persistant. |
| Événement ancien reçu plus tard | Ne pas écraser aveuglément un état récent. | État de référence et règle de transition. |
| Traitement lourd | Réception durable puis travail différé. | État de file et résultat du worker. |
| Livraison manquante | Rapprocher et reprendre selon les règles du fournisseur. | Écart identifié et correction vérifiée. |
Construire une réception vérifiable
- Vérifiez HTTPS, signature et protection contre le rejeu selon le protocole du fournisseur. Pour Stripe, la signature se vérifie sur le corps brut ; transformer le JSON auparavant peut invalider la vérification.
- Enregistrez durablement l’événement ou son traitement avant l’accusé de réception approprié. Distinguez identifiant de livraison, identifiant d’événement et clé d’idempotence de l’action métier.
- Testez doublons, événements désordonnés, interruption du worker et redémarrage. Relisez l’état officiel de l’objet si un événement ancien ne permet pas une décision sûre.
Organiser reprise et rapprochement
Documentez tentatives, délais, événements non traités et procédure de rapprochement avec le fournisseur. Un accusé rapide peut masquer un échec ultérieur du traitement. Surveillez donc aussi l’action métier finale et limitez secrets et données personnelles dans les journaux.
Références primaires
Webhooks : traiter l’événement plus d’une fois sans dommage
Une notification peut être répétée après délai ou réponse perdue. La fiabilité dépend d’une vérification de provenance, d’un identifiant d’événement et d’un traitement qui distingue nouveau message et doublon.
- Vérifier l’authenticité de chaque appel selon le mécanisme du fournisseur.
- Tester retry, doublon et arrivée dans un ordre différent.
- Répondre avec un accusé cohérent après traitement ou mise en file durable.
Référence primaire : IETF RFC 9457 — Problem Details for HTTP APIs. Méthode connexe : consulter le guide pratique.