Événement
Enregistrement d’une modification concernant un paiement, une session de jeu, un contrôle KYC, un bonus, un profil joueur ou un autre objet.
Documentation / Webhooks
Webhooks et livraison des événements
Mettez en place une livraison fiable des statuts et événements entre les systèmes : de la création du message et la vérification de la signature jusqu’à l’accusé de réception, la nouvelle livraison et la surveillance des erreurs.
Événements
statuts et modifications
Signature
vérification de l’authenticité
Nouvelles tentatives
nouvelle livraison
Surveillance
historique et diagnostic
Flux d’événements
De la création à l’accusé de réception
01
Créer un événement
Indiquer l’identifiant, le type, l’heure, l’objet, le statut et les données associées.
02
Signer et envoyer
Envoyer l’événement via HTTPS avec une signature et un délai d’attente limité.
03
Accuser réception
Après vérification, enregistrer l’événement et renvoyer rapidement une réponse HTTP de succès.
04
Réessayer en cas d’erreur
Relancer la livraison avec des intervalles croissants et conserver les événements non livrés pour analyse.
Vue d’ensemble
Un webhook signale un changement d’état
L’expéditeur peut relancer la livraison ; le destinataire doit donc vérifier la source, accuser réception et n’appliquer chaque événement qu’une seule fois.
Accusé de réception
Le destinataire renvoie une réponse HTTP de succès après avoir vérifié et enregistré l’événement de manière fiable.
Récupération
La nouvelle livraison et le rapprochement permettent de restaurer les données après une indisponibilité temporaire de l’un des systèmes.
Structure de l’événement
Contenu attendu d’un événement
Une structure de message cohérente simplifie la vérification, le routage, la protection contre les doublons et la prise en charge de différents types d’événements.
Identifiant de l’événement
Valeur unique utilisée par le système pour reconnaître une nouvelle livraison et retrouver l’historique de traitement.
Type d’événement
Nom clair et stable qui définit la modification survenue et la manière de la traiter.
Heure de création
Date et heure de création de l’événement, dans le format et le fuseau horaire convenus.
Objet associé
Type et identifiant du paiement, joueur, tour, demande, bonus ou autre objet.
Version du schéma
Un numéro de version permet de modifier en toute sécurité la structure du message sans perturber les intégrations actives.
Corrélation de l’opération
Identifiant de la requête, transaction, session ou chaîne d’actions associées d’origine.
Contexte
Marque, projet, marché, environnement, fournisseur et autres données nécessaires au bon routage.
Données de l’événement
Ensemble minimal de champs nécessaires pour traiter la modification ou effectuer une requête API ultérieure.
Signature et vérification
Vérification de l’authenticité et de l’intégrité de l’événement
Avant de modifier des données, le destinataire vérifie la connexion sécurisée, la signature, l’heure de création et l’identifiant unique de l’événement.
01
Capturer le message brut
Vérifier la signature sur le corps brut de la requête avant de modifier le format JSON.
02
Vérifier l’horodatage
Rejeter la requête si l’heure de l’événement se situe en dehors de la fenêtre autorisée.
03
Vérifier la signature
Utiliser le secret convenu et l’algorithme HMAC ou de signature numérique.
04
Vérifier l’identifiant
Confirmer que l’événement n’a pas déjà été appliqué et enregistrer le résultat de la vérification.
Livraison et nouvelles tentatives
Réponses HTTP et nouvelle livraison
L’expéditeur doit distinguer une réception réussie, une erreur temporaire et un échec permanent, tandis que le destinataire doit répondre rapidement et sans ambiguïté.
Réponse HTTP de succès
Confirme que l’événement a été vérifié et enregistré de manière fiable pour un traitement ultérieur.
Délai d’attente limité
N’effectuez pas de traitement long avant de répondre à l’expéditeur — enregistrez d’abord l’événement.
Nouvelle livraison
Relancer la livraison après une erreur réseau temporaire, une indisponibilité ou une absence de réponse.
Intervalle croissant entre les tentatives
Augmenter progressivement le délai entre les tentatives afin d’éviter une charge supplémentaire.
File des événements non livrés
Après épuisement de toutes les tentatives, conserver l’événement pour diagnostic et traitement manuel.
Nouvelle livraison manuelle
Un opérateur peut renvoyer un événement sélectionné sans créer une nouvelle opération.
Surveillance de la livraison
Suivre le nombre de tentatives, les réponses, la dernière erreur et l’heure de la prochaine livraison.
Alertes
Alerter l’équipe lorsque les erreurs augmentent, que les tentatives sont épuisées ou que les événements s’accumulent dans la file.
Traitement des événements
Protection contre les doublons et ordre des statuts
Le destinataire ne doit pas dépendre d’une livraison unique ni d’un ordre strict des événements.
Appliquer une seule fois
Enregistrer l’identifiant de l’événement avant de modifier les données.
Accuser réception d’un événement répété sans effectuer un nouveau débit, crédit ou changement d’état.
Relier l’événement à l’objet et à son état actuel.
Enregistrer l’événement et la modification métier comme une seule opération cohérente.
Ordre et fraîcheur des données
Comparer l’horodatage, le numéro de séquence ou la version de l’événement.
Ne pas ramener un objet à un état obsolète lorsqu’un événement plus ancien arrive en retard.
N’autoriser que les transitions valides entre statuts.
En cas de doute, demander l’état actuel de l’objet via l’API.
Tests
Éléments à tester avant le lancement
Tester la livraison réussie, les signatures invalides, les doublons, les réponses lentes, les événements reçus dans le désordre et la récupération après une défaillance.
Signature invalide
Message modifié, clé inconnue, horodatage expiré et algorithme non pris en charge.
Nouvelle livraison
Le même événement arrive plusieurs fois avant et après la fin du traitement.
Réponse lente
Le destinataire met trop de temps à répondre, la connexion est interrompue ou l’accusé de réception n’atteint pas l’expéditeur.
Traitement dans un ordre différent
Un statut final arrive avant un statut intermédiaire et un événement plus ancien est livré après un événement plus récent.
Point de terminaison indisponible
Tester les erreurs HTTP 5xx, le DNS, TLS, les limites de débit et l’épuisement complet des tentatives.
Historique des livraisons
Toutes les tentatives, réponses, erreurs et résultats de nouvelle livraison manuelle doivent pouvoir être recherchés par identifiant d’événement.
Liste de contrôle avant lancement
La livraison en production est activée après vérification de la sécurité, de la protection contre les doublons, de la nouvelle livraison et de la surveillance des erreurs.
Les environnements de test et de production utilisent des points de terminaison et des secrets de signature différents.
La signature est vérifiée sur le message brut en même temps que son heure de création.
L’identifiant de l’événement est enregistré et protège les opérations contre une exécution multiple.
Le destinataire renvoie rapidement une réponse HTTP de succès après avoir enregistré l’événement.
Les nouvelles tentatives, les intervalles croissants et la nouvelle livraison manuelle sont configurés.
L’historique de livraison et la recherche par identifiant sont accessibles à l’équipe d’assistance.
Besoin de mettre en place une livraison fiable des événements ?
Transmettez la liste des événements, les points de terminaison de réception et les règles de transition des statuts. APIACE vous aidera à définir la structure des messages, la vérification des signatures, la nouvelle livraison et la surveillance des erreurs.