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 gérer pleinement le magasin en jeu et les paiements, il est nécessaire d’implémenter le traitement des principaux webhooks :

Le schéma ci-dessous illustre le processus d’achat et de retour d’objets en utilisant les webhooks combinés.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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 et accédez à la section Settings > Webhooks.
2. Dans le champ Webhook server, indiquez l’URL du serveur sur lequel vous souhaitez recevoir les webhooks, au format https://example.com. Vous pouvez également utiliser l’URL fournie par un outil de test des webhooks.

3. 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.
4. 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, activez les bascules nécessaires. À côté de chaque autorisation, la liste des webhooks affectés par les paramètres s’affiche.

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Settings > Webhooks.
2. Appuyez sur Disable webhooks.

Tester les webhooks dans le Compte éditeur

Après l’activation des webhooks dans le projet, une section permettant de les tester s’affiche dans le Compte éditeur, sous les paramètres avancés.

Vous pouvez tester les webhooks suivants :

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 d’objet. Si le type d’objet sélectionné n’est pas configuré dans le projet, un bouton s’affichera pour accéder à la configuration des objets.
3. Remplissez les champs nécessaires :
   • Xsolla order ID — ID de l’ordre côté Xsolla. Lors des tests, utilisez n’importe quelle combinaison de chiffres.
   • Xsolla invoice ID — identifiant de la transaction côté Xsolla. Lors des tests, utilisez n’importe quelle combinaison de chiffres.
   • Items — objets pour lesquels vous souhaitez recevoir des informations dans le webhook. Sélectionnez l’UGS des objets dans le menu déroulant et indiquez la quantité. Pour ajouter plusieurs objets du même type, appuyez sur + et ajoutez-les dans une nouvelle ligne.
   • User ID — lors des tests, utilisez n’importe quelle combinaison de lettres et de chiffres.
   • Invoice ID — identifiant de transaction côté jeu. Lors des tests, utilisez n’importe quelle combinaison de lettres et de chiffres. Ce paramètre n’est pas obligatoire pour un paiement réussi, mais vous pouvez le passer pour lier l’identifiant de transaction côté jeu à celui côté Xsolla.
   • Amount — montant du paiement. Lors des tests, utilisez n’importe quelle valeur numérique.
   • Currency — sélectionnez une devise dans la liste déroulante.
4. Cliquez sur Test webhook.

Les webhooks Successful payment for order, Order cancellation et User validation, avec les données spécifiées, sont envoyés a l’URL fournie. Les résultats du test de chaque type de webhook s’affichent sous le bouton Test webhook. Pour chaque webhook, vous devez configurer le traitement des deux scenarios : un scenario reussi et un scenario avec 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.

La logique de nouvelle tentative pour les webhooks Payment et Refund est décrite sur la page dédiée à chaque webhook.

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 Paiement et Paiement de commande réussi ne sont pas envoyés.

Configuration des informations sur les objets dans les webhooks

Vous pouvez configurer les données relatives aux objets inclus dans les webhooks Paiement de commande réussi et Annulation de commande via le tableau items.

Activation de l'inclusion de paramètres supplémentaires

Permet d’inclure des paramètres supplémentaires indiquant :

• si l’objet est gratuit (is_free ) ;
• si l’objet est un bonus (is_bonus) ;
• si l’objet fait partie d’un lot (is_bundle_content).

Pour recevoir ces paramètres, vous devez mettre à jour vos webhooks vers la version 2 en utilisant l’appel API Mettre à jour les informations sur les paramètres du webhook. Dans la version 1 (par défaut), ces paramètres ne sont pas disponibles.

Exemple de tableau items avec des paramètres supplémentaires :

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Désactivation de l'inclusion du contenu du lot

Par défaut, les webhooks incluent tous les objets du lot sous forme de liste d’objets individuels. Vous pouvez configurer le webhook pour n’inclure que le lot lui-même, sans énumérer son contenu.

Dans ce cas, les objets contenus dans le lot ne sont pas inclus dans le tableau items. Par exemple, dans le tableau ci-dessus, l’objet portant l’UGS com.xsolla.gold_1, qui fait partie du lot, est exclu.

Exemple de tableau items lorsque le contenu du lot est désactivé :

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Pour désactiver l’inclusion du contenu des lots, contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com.