Configurer des webhooks

Les webhooks fonctionnent comme des notifications pour les événements système. Lorsqu’un événement spécifique se produit, Xsolla envoie une requête HTTP à votre application, généralement sous la forme d’une requête POST au format JSON, transmettant les données de l’événement.

Exemples d’événements :

• interaction de l’utilisateur avec le catalogue des objets ;
• paiement ou annulation d’une commande.

Liste des webhooks

Pour passer à la nouvelle option avec réception de webhooks combinés, contactez vos responsables de la réussite client ou envoyez un e-mail à csm@xsolla.com.

Pour gérer pleinement le magasin en jeu et les paiements, il est nécessaire d’implémenter le traitement des principaux webhooks :

Si la personnalisation du catalogue des objets est implémentée côté application, implémentez le traitement de Personnalisation du catalogue côté partenaire.

Configurer les webhooks dans le Compte éditeur

Pour activer la réception des webhooks :

1. Ouvrez le projet dans le Compte éditeur.
2. Dans le menu latéral, cliquez sur Project settings et accédez à l’onglet Webhooks.
3. Dans le champ Webhook server, spécifiez l’URL du serveur où vous souhaitez recevoir les webhooks, dans le format https://example.com. Vous pouvez également spécifier l’URL que vous trouvez dans un outil de test de webhooks.

4. Une clé secrète pour signer les webhooks du projet est générée par défaut. Si vous souhaitez générer une nouvelle clé secrète, cliquez sur l'icône d'actualisation.
5. Cliquez sur Enable webhooks.

Lorsque vous enregistrez l’URL dans le champ Webhook server, explorez la section Advanced settings pour accorder les autorisations de recevoir des informations détaillées via les webhooks. Pour ce faire, réglez les bascules correspondantes sur On. À côté de chaque autorisation, la liste des webhooks affectés par les paramètres s’affiche.

Pour désactiver la réception des webhooks :

1. Ouvrez le projet dans le Compte éditeur.
2. Dans le menu latéral, cliquez sur Project settings et accédez à l’onglet Webhooks.
3. Cliquez sur Disable webhooks.

Tester les webhooks dans le Compte éditeur

Si les webhooks sont configurés avec succès, un bloc de test de webhooks s’affiche sous le bloc de configuration des webhooks.

La section de test dans le Compte éditeur varie en fonction de l’option de réception du webhook.

Le processus de test du scénario avec des webhooks combinés est décrit ci-dessous.

Dans l’onglet Payments and Store, vous pouvez tester les webhooks suivants :

• Validation utilisateur (user_validation) ;
• Paiement de commande réussi (order_paid) ;
• Annulation de commande (order_canceled).

Pour tester :

1. Dans la section de test des webhooks, accédez à l’onglet Payments and Store.
2. Dans le menu déroulant, sélectionnez le type de bien. Si le type de bien sélectionné n’est pas configuré dans le Compte éditeur, cliquez :
   • Connect — si le module contenant des biens de ce type n’est pas connecté ;
   • Configure — si vous avez connecté le module précédemment, mais que vous n’avez pas terminé la configuration.
   Lorsque vous cliquez sur le bouton, vous serez redirigé vers la section du Compte éditeur correspondant au type du bien sélectionné. Après avoir créé le bien, revenez à la section de test du webhook et passez à l’étape suivante.
3. Remplissez les champs nécessaires :
   1. Entrez les UGS des biens de la liste déroulante et indiquez le montant. Pour sélectionner plusieurs biens de même type, cliquez sur + et ajoutez-les dans une nouvelle ligne.
   2. User ID — lors des tests, utilisez n’importe quelle combinaison de lettres et de chiffres.
   3. Public user ID — ID connu de l’utilisateur, par exemple, une adresse e-mail ou un pseudo. Ce champ est affiché si l’ID utilisateur public est activé dans votre projet dans la section Pay Station > Paramètres.
   4. Entrez une valeur aléatoire dans le champ Xsolla Order ID.
   5. Xsolla Invoice ID — ID de transaction côté Xsolla. Lors des tests, utilisez une valeur numérique aléatoire.
   6. Invoice ID — ID de transaction côté jeu. Lors des tests, n’importe quelle combinaison de lettres et de chiffres est admissible. Ce paramètre n’est pas nécessaire pour un paiement réussi, mais vous pouvez le transmettre pour lier l’ID de transaction de votre côté à l’ID de transaction côté Xsolla.
   7. Amount — montant du paiement. Lors des tests, vous pouvez utiliser une valeur numérique aléatoire.
   8. Currency — sélectionnez une devise dans la liste déroulante.
4. Cliquez sur Test webhook.

Les webhooks Validation utilisateur, Paiement de commande réussi et Annulation de commande avec les données spécifiées sont envoyés à l’URL fournie. Les résultats du test de chaque type de webhook sont affichés sous les boutons Test. Si l’ID utilisateur public est activé dans votre projet, les résultats de la recherche utilisateur s’affichent également.

Il est nécessaire de configurer le traitement des deux scénarios pour chaque webhook : un scénario réussi et un scénario avec une erreur.

Écouteur webhook

L’écouteur webhook est un code de programme qui permet de recevoir des webhooks entrants à une adresse URL spécifiée, de générer une signature et d’envoyer une réponse au serveur webhook de Xsolla.

Génération d'une signature

Lorsque vous recevez un webhook, vous devez vous assurer de la sécurité de la transmission des données. Pour cela, vous devez générer une signature à partir des données du webhook et vérifier qu’elle correspond à la signature envoyée dans l’en-tête de la requête HTTP.

Pour générer une signature :

1. Concaténez le JSON du corps de la requête avec la clé secrète du projet.
2. Appliquez la fonction de hachage cryptographique SHA-1 à la chaîne obtenue lors de la première étape.

Envoi de réponses au webhook

Pour confirmer la réception du webhook, votre serveur doit renvoyer :

• Un code HTTP 200, 201 ou 204 en cas de réponse positive ;
• Un code HTTP 400 avec description du problème au cas où l’utilisateur spécifié n’a pas été trouvé ou une signature non valide a été passée.

Votre gestionnaire de webhooks peut également renvoyer un code 5xx en cas de problèmes temporaires sur votre serveur.

Si le serveur Xsolla ne reçoit pas de réponse aux webhooks Paiement de commande réussi et Annulation de commande ou s’il reçoit une réponse contenant un code 5xx, les webhooks sont renvoyés selon le calendrier suivant :

• 2 tentatives à intervalles de 5 minutes ;
• 7 tentatives à intervalles de 15 minutes ;
• 10 tentatives à intervalles de 60 minutes.

Un maximum de 20 tentatives d’envoi de webhooks sont effectuées dans les 12 heures suivant la première tentative.

Si le serveur Xsolla ne reçoit pas de réponse aux webhooks Paiement ou Remboursement, ou s’il reçoit une réponse contenant un code 5xx, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectuées dans les 12 heures.

Si le serveur Xsolla ne reçoit pas de réponse au webhook Validation utilisateur ou s’il reçoit une réponse contenant un code 400 ou 5xx, le webhook Validation utilisateur n’est pas renvoyé.

Dans ce cas, une erreur est affichée à l’utilisateur et les webhooks Payment et Successful payment of the order ne sont pas envoyés.

Dernière mise à jour: 23 Janvier 2025