Gérer les callbacks en double et les tentatives API
Une API peut envoyer une requête, attendre sans réponse, puis recommencer alors que la première opération a peut-être été enregistrée. Un agrégateur de jeux ou une file d'événements peut aussi remettre le même callback. Si la plateforme de casino interprète chaque livraison comme un nouveau débit, crédit, remboursement ou avantage, les écarts financiers deviennent réels. La livraison d'un message doit donc être distinguée de la transaction métier, avec un seul effet durable dans le grand livre de l'opérateur. Les fournisseurs ne partagent pas tous les mêmes identifiants, réponses aux doublons ou règles de relance. Ce guide présente un traitement authentifié et atomique, les réponses sûres, les événements hors ordre, le rapprochement et les tests indispensables. [1] [2] [4]
Publié le
Les messages peuvent revenir; l'effet financier ne doit pas être répété.
Sommaire
Pourquoi un même callback arrive-t-il plusieurs fois ?
L'émetteur peut perdre la réponse HTTP alors que le destinataire a terminé l'opération. Il réessaie, ou une file remet un message dont l'accusé de réception n'a pas été enregistré. La livraison au moins une fois autorise ces doublons; l'ordre n'est pas garanti par défaut. Un nouvel envoi ne prouve ni une fraude ni une seconde transaction métier. [4] [5]
Dans un casino, un débit, crédit ou retour de fonds ne doit pas être exécuté deux fois à cause de la livraison. L'effet métier, la réception du callback et la réponse HTTP ont des cycles indépendants. St8 et 7SoftTech utilisent des ID de transaction pour reconnaître les répétitions, avec des réponses et cas limites distincts. [1] [2]
Quels identifiants composent une clé d'idempotence ?
Distinguez l'ID de livraison, la source authentifiée, la transaction métier, le type d'opération, l'original éventuellement annulé et la manche de jeu. C'est l'identité métier prévue par le contrat qui doit empêcher les écritures répétées. Son périmètre peut inclure fournisseur et opérateur; des services sans lien peuvent réutiliser le même ID. [1] [2] [3]
Identifiant
Fonction
Règle
Fournisseur / client
Définir l'espace de clés
Vérifier la source
ID transaction
Nommer le mouvement
Unicité selon le contrat
Type d'opération
Débit, crédit, annulation
Respecter le modèle API
ID événement
Nommer une livraison
Pas toujours clé financière
ID d'origine
Relier l'annulation
Valider la référence
Manche et joueur
Contexte métier
Ne remplace pas la transaction
Associez à la clé une empreinte stable du contenu et un état persistant. Le même ID avec un montant, une devise ou un joueur différent est un conflit à traiter selon le contrat, jamais une autorisation de nouvelle écriture. AWS décrit ce principe de même intention pour les relances d'API. [3] [4]
Que vérifier avant de traiter un doublon ?
Vérifiez d'abord la signature ou la preuve d'authentification exigée par le fournisseur, sur les octets attendus. Autorisez ensuite la source pour l'opérateur, le portefeuille, le joueur, la devise, l'action et la session concernés. Un ID connu envoyé par une source non authentifiée ne constitue pas une preuve d'exécution. OWASP décrit la sécurisation des webhooks avant déduplication. [1] [6]
Contrôler la signature, la fenêtre de validité et la protection anti-rejeu selon le protocole du fournisseur.
Associer le fournisseur authentifié au bon opérateur, joueur, portefeuille et devise.
Valider ID, précision du montant, action et référence à la transaction d'origine.
Comparer l'empreinte du message au contenu mémorisé avant de déclarer un doublon.
Conservez des ID, horodatages et empreintes utiles à l'audit, sans secrets ni données personnelles superflues. Ne renvoyez pas une confirmation positive à une requête falsifiée sous prétexte que son ID existe déjà. [2] [6]
Quel est le parcours complet d'un callback fiable ?
Après authentification, le service recherche ou réserve la clé métier unique, compare les paramètres, applique le mouvement autorisé et conserve le résultat dans la même opération durable de base de données. Une répétition identique retrouve cette décision au lieu de modifier encore le portefeuille. Les cas dont l'issue est incertaine vont au rapprochement. [1] [4] [6]
Authentifier le callback, son fournisseur et le joueur interne autorisé.
Construire la clé métier prévue et vérifier les références d'annulation.
Trouver ou réserver atomiquement l'opération, comptabiliser une seule fois et stocker l'issue.
Répondre selon le fournisseur ou rapprocher le cas ambigu sans créer d'autre mouvement.
⊕Agrandir le schémaPlusieurs tentatives de livraison peuvent désigner la même transaction durable.
Le commit de la base et la réponse HTTP ne constituent généralement pas une seule transaction atomique entre systèmes. Il faut donc gérer le cas où l'écriture est achevée, mais la réponse est perdue : le fournisseur relancera alors un mouvement pourtant enregistré. [4] [7]
Comment garantir une seule écriture financière en base ?
Imposez une contrainte d'unicité réelle sur la clé métier et réalisez la réception, l'effet portefeuille et la conservation de l'issue sous une frontière transactionnelle adaptée. Un SELECT suivi plus tard d'un UPDATE ne protège pas des accès concurrents : deux workers peuvent observer simultanément une clé absente. L'unicité et les verrous doivent être garantis par la base. [3] [4]
État rencontré
Action sûre
Scénario à tester
Clé nouvelle
Écrire et conserver une fois
Deux premiers appels concurrents
Terminée, même contenu
Restituer l'issue
Aucun second crédit
En cours
Attendre ou rapprocher
Workers concurrents
Même clé, contenu différent
Rejeter le conflit
Montant ou joueur modifié
Annulée avant commit
Relancer sous contrôle
Crash après réservation
Une boîte de réception d'événements durable est utile, mais l'événement reçu n'est pas la preuve d'une écriture financière. Conservez état de transaction, référence comptable et résultat immuable. Selon le fournisseur, l'annulation possède sa propre identité ou modifie l'opération liée. [1] [3]
Quelle réponse donner à un doublon ou à un conflit ?
Pour un doublon authentifié et déjà traité durablement, renvoyez l'issue initiale ou le code précis demandé par le fournisseur. Il n'existe pas de règle universelle imposant HTTP 200, 409 ou un code JSON identique. St8, 7SoftTech et GR8 Tech ont des contrats de réponse différents. [1] [2] [3]
Garder une règle de réponse stable pour le même ID et la même opération métier.
Refuser le même ID avec une devise, un montant, un joueur ou une action contradictoire.
Après un commit dont la réponse est perdue, restituer la décision sans autre mouvement.
Distinguer rejet métier définitif et panne technique transitoire pour arrêter ou relancer.
N'utilisez pas un ancien solde si le partenaire attend le solde actuel, et n'inventez pas de code de doublon. Vérifiez les règles exactes de répétition, d'annulation et de rejet. Le seul fait d'utiliser POST ne rend pas une relance automatique sûre. [2] [3] [7]
Quand relancer, attendre ou arrêter les requêtes ?
La décision dépend du contrat d'idempotence et de la nature du problème. Un timeout ou une erreur serveur temporaire peut laisser l'issue de la première tentative inconnue. Une signature invalide, un message mal formé ou un refus métier final ne doit pas être répété indéfiniment. Prévoyez des essais bornés, un délai croissant avec jitter et un chemin de rapprochement. [4] [6] [7]
Situation
Action préférable
Motif
Timeout après envoi
Consulter ou réessayer le même ID
Commit inconnu
Erreur 5xx / limite temporaire
Réessayer de façon bornée
Incident transitoire
Signature invalide
Rejeter et alerter
Source non authentifiée
Refus métier définitif
Arrêter selon le contrat
Relance sans effet positif
Accusé perdu après commit
Restituer l'issue conservée
Éviter un nouveau débit
Séparez la file automatique de relance des interventions humaines. Les équipes doivent savoir quand une répétition est permise, quand il faut interroger le statut et quand escalader. Ne changez pas l'ID métier pour forcer une transaction incertaine à passer une seconde fois. [3] [4]
Que faire si les événements arrivent dans le désordre ?
Une file peut changer l'ordre des événements; une annulation peut arriver avant le débit qu'elle vise. Certains contrats imposent de conserver une marque de révocation afin que le débit initial reçu plus tard ne soit jamais exécuté. D'autres fournisseurs utilisent des états différents. Il serait dangereux d'appliquer les codes particuliers d'un fournisseur à toutes les API. [1] [2] [5]
Conserver la référence d'origine et l'état métier, pas seulement l'heure de réception.
Documenter les transitions autorisées entre débit, crédit, annulation et correction pour chaque fournisseur.
Créer une marque durable d'annulation anticipée lorsque le contrat le prévoit.
Mettre les références non résolues en rapprochement, sans inventer de mouvements.
L'ordre d'arrivée ne définit pas l'ordre métier. Ne triez pas les mouvements uniquement selon l'horodatage distant. Identité de transaction, dépendances entre opérations et source comptable faisant autorité doivent guider la décision. [2] [5]
Comment rapprocher les relances après une panne ?
Un callback peut être reçu mais échouer avant la comptabilisation, ou être comptabilisé tout en perdant son accusé. Suivez séparément la livraison technique et l'écriture réelle. Rapprochez les clés incertaines du grand livre de l'opérateur et des données fournisseur, avec une procédure explicite en cas de conflit. Actualiser simplement le solde affiché ne suffit pas. [1] [3] [4]
Mesurer essais, doublons reconnus, signatures refusées, écarts de payload et file de rapprochement par fournisseur.
Alerter sur timeouts fréquents, opérations bloquées, annulations anticipées et écarts comptables.
Limiter la relance manuelle aux personnes autorisées avec ID d'origine et motif audité.
Comparer le grand livre et les relevés fournisseur avant toute écriture compensatrice.
Conserver le registre de déduplication assez longtemps pour les délais contractuels de relance et de litige.
Évitez de transmettre données de paiement ou personnelles brutes aux outils d'analytique générale. Les identifiants sûrs, empreintes, dates, changements d'état et interventions permettent l'audit avec des accès restreints. Affichez séparément le nombre de doublons livrés et les écarts financiers réels. [4] [6]
Quels tests d'acceptation prouvent la sécurité des relances ?
Un pari et un gain traités correctement une fois ne démontrent pas la résistance aux relances. Les essais doivent couvrir IDs répétés, payloads contradictoires, workers simultanés, réponses perdues, annulations et messages tardifs selon les règles du partenaire. 7SoftTech documente des scénarios de certification pour bet, win et cancel répétés. [2]
Exécuter un débit ou crédit, renvoyer le même callback signé et vérifier une seule écriture.
Renvoyer l'ID avec un autre montant, joueur ou devise et vérifier le refus contrôlé.
Mettre deux livraisons en concurrence, simuler la perte du reply après commit et relire l'issue.
Livrer une annulation avant son origine et contrôler la transition prévue par le fournisseur.
Simuler indisponibilité et retards, puis rapprocher grand livre et traces d'audit.
Avant production, validez avec chaque partenaire les réponses, le périmètre des clés, la durée des relances et les règles de reversal. L'objectif n'est pas d'empêcher toute livraison répétée, mais d'obtenir une seule bonne conséquence financière pour chaque opération autorisée, malgré les délais et erreurs de réseau. [1] [3] [4]