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

Exemples d'événement :

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

Lorsqu'un événement se produit, Xsolla envoie une notification à votre système via un webhook. Vous pouvez ensuite effectuer des actions telles que :

• recharger le solde de l'utilisateur ;
• effectuer un remboursement de paiement ;
• créditer des objets au compte de l'utilisateur ou en débiter ;
• commencer à fournir un abonnement ;
• bloquer un utilisateur en cas de soupçon de fraude.

Exemple de flux de travail d'un webhook de traitement de paiement :

Guide vidéo pour l'intégration des webhooks Xsolla :

Paramètres des webhooks lors de l'interaction avec les produits et solutions Xsolla :

Produit/Solution	Obligatoire/Facultatif	À quoi servent les webhooks ?
Payments	Obligatoire	Validation utilisateur. Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement. Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.
In-Game Store	Obligatoire	Validation utilisateur. Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement. Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande.
Game Sales	Facultatif	Pour la vente de clés de jeu, la validation utilisateur et le crédit des objets ne sont pas nécessaires. Connectez des webhooks si vous souhaitez recevoir des informations sur des événements tels que le paiement ou l'annulation de commandes. Assurez-vous de traiter tous les webhooks entrants requis.
Subscriptions	Facultatif	Réception d'informations sur la création, la mise à jour ou l'annulation d'abonnements. Vous pouvez également demander des informations via API.
Web Shop	Obligatoire	Validation utilisateur. Réception d'informations détaillées sur la transaction en cas de paiement réussi ou de remboursement de paiement. Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande. Authentification utilisateur, si vous utilisez l'authentification par ID utilisateur. Vous pouvez également utiliser l'authentification utilisateur via Xsolla Login.
Digital Distribution Hub	Obligatoire	Validation utilisateur. Liaison de l'ID de transaction côté Xsolla à l'ID de transaction de votre système. Transfert de paramètres de transaction supplémentaires dans la commande. Octroi des objets achetés à l'utilisateur et déduction de ceux-ci en cas d'annulation de la commande. Reportez-vous à la documentation pour obtenir plus d'informations sur la configuration des webhooks pour Digital Distribution Hub.

Si vous utilisez des produits et des solutions nécessitant de travailler avec des webhooks, activez et testez ces webhooks dans votre Compte éditeur, puis configurez leur traitement. Lorsque des événements spécifiques se produisent, les webhooks sont envoyés de manière séquentielle. Assurez-vous de traiter tous les webhooks requis, sinon les suivants ne seront pas envoyés. La liste des webhooks requis est présentée ci-dessous.

Deux options d'envoi de webhook sont configurées côté Xsolla lors de l'achat et du retour de biens sur le site : les informations sur les données de paiement et de transaction, ainsi que celles sur les biens achetés, peuvent être envoyées séparément ou être combinées dans un seul webhook.

Réception d'informations dans des webhooks combinés :

Si vous avez enregistré un Compte éditeur après le 22 janvier 2025, vous recevez toutes les informations dans les webhooks Paiement de commande réussi (order_paid) et Annulation de commande (order_canceled). Dans ce cas, vous n'avez pas besoin de traiter les webhooks Paiement (payment) et Remboursement (refund).

Réception d'informations dans des webhooks distincts :

Si vous avez enregistré un Compte éditeur au plus tard le 22 janvier 2025, vous recevez les webhooks suivants  :

• Paiement (payment) et Remboursement (refund) avec des informations sur les données de paiement et de transaction.
• Paiement de commande réussi (order_paid) et Annulation de commande (order_canceled) avec des informations sur les objets achetés.

Vous devez traiter tous les webhooks entrants. Pour passer à la nouvelle option de réception des webhooks combinés, contactez vos responsables de la réussite client ou envoyez un e-mail à csm@xsolla.com.

Pour assurer le fonctionnement complet du magasin en jeu et de la gestion des paiements, il est nécessaire d'implémenter le traitement des principaux webhooks.

Si vous recevez des webhooks combinés :

Nom et type du webhook	Description
Validation utilisateur > Validation utilisateur (user_validation)	Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu.
Services de jeux > Webhooks combinés > Paiement de commande réussi (order_paid)	Il contient les données du paiement et de la transaction ainsi que des informations sur les biens achetés. Utilisez les données du webhook pour octroyer les objets à l'utilisateur.
Services de jeux > Webhooks combinés > Annulation de commande (order_canceled)	Il contient les données du paiement annulé et de la transaction ainsi que des informations sur les biens achetés. Utilisez les données du webhook pour retirer les objets achetés.

Si vous recevez des webhooks distincts :

Nom et type du webhook	Description
Validation utilisateur > Validation utilisateur (user_validation)	Est envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est enregistré dans le jeu.
Payments > Paiement (payment)	Il contient les données du paiement et de la transaction.
Services de jeux > Webhooks distincts > Paiement de commande réussi (order_paid)	Il contient des informations sur les biens achetés. Utilisez les données du webhook pour octroyer les objets à l'utilisateur.
Payments > Remboursement (refund )	Il contient les données du paiement et de la transaction.
Services de jeux > Webhooks distincts > Annulation de commande (order_canceled)	Il contient des informations sur les biens achetés et l'ID de la transaction annulée. Utilisez les données du webhook pour retirer les objets achetés.

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

Pour gérer les plans d'abonnement de manière automatique, il est nécessaire d'implémenter le traitement des principaux webhooks :

• Validation utilisateur (user_validation) — envoyé à différentes étapes du processus de paiement pour s'assurer que l'utilisateur est bel et bien enregistré dans le jeu.
• Paiement (payment) — envoyé lorsqu'une commande est payée et contient les données de paiement ainsi que les détails de la transaction.
• Abonnement créé (create_subscription) — envoyé lorsqu'un webhook Paiement est traité avec succès ou lorsque l'utilisateur achète un abonnement avec une période d'essai. Il contient les détails de l'abonnement acheté ainsi que les données de l'utilisateur. Utilisez les données du webhook pour ajouter l'abonnement à l'utilisateur.
• Abonnement mis à jour (update_subscription) — envoyé lorsqu'un abonnement est renouvelé ou modifié, lorsqu'un webhook Paiement est traité avec succès. Il contient les détails de l'abonnement acheté et les données de l'utilisateur. Utilisez les données du webhook pour prolonger l'abonnement de l'utilisateur ou modifier les paramètres de l'abonnement.
• Remboursement (refund) — envoyé lorsqu'une commande est annulée et contient les données du paiement annulé ainsi que les détails de la transaction.
• Abonnement annulé (cancel_subscription) — envoyé lorsqu'un webhook Remboursement est traité avec succès ou lorsque l'abonnement est annulé pour une autre raison. Il contient des informations sur l'abonnement et les données de l'utilisateur. Utilisez les données du webhook pour déduire les abonnements achetés de l'utilisateur.

Pour activer la réception des webhooks :

1. Dans le projet dans le Compte éditeur, accédez à la section Paramètres du projet > Webhooks.
2. Dans le champ Webhook server, spécifiez l'URL du serveur où vous souhaitez recevoir des webhooks au format https://example.com. Vous pouvez également indiquer l'URL que vous trouvez dans un outil de test de 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.

Pour désactiver la réception de webhooks :

1. Dans le projet dans le Compte éditeur, accédez à la section Paramètres du projet > Webhooks.
2. Cliquez sur Disable webhooks.

Pour les webhooks de la section Payments and Store, des paramètres avancés sont disponibles. Ils apparaîtront automatiquement sous le bloc General settings après que vous aurez cliqué sur le bouton Get webhooks.

Dans cette section, vous pouvez configurer la réception d'informations supplémentaires dans les webhooks. Pour ce faire, réglez les bascules correspondantes en position active. La ligne de chaque autorisation indique les webhooks qui seront affectés par la modification des paramètres.

Bascule	Description
Afficher infos sur le compte de paiement enregistré	Les informations relatives au mode de paiement enregistré sont passées à l'objet personnalisé payment_account.
Afficher infos sur transactions effectuées via modes de paiement enregistrés	Les informations sont passées dans les paramètres personnalisés suivants du webhook : saved_payment_method: 0 — le mode de paiement enregistré n'a pas été utilisé ; 1 — le mode de paiement a été enregistré lors du paiement en cours ; 2 — le mode de paiement précédemment enregistré est utilisé. payment_type: 1 — paiement unique ; 2 — paiement récurrent.
Ajouter l'objet de la commande au webhook	Les informations relatives à la commande sont passées dans l'objet order du webhook Paiement.
Envoyer paramètres utilisateur nécessaires seulement sans données sensibles	Seules les informations suivantes sur l'utilisateur sont passées dans le webhook : ID ; pays.
Envoyer paramètres personnalisés	Les informations relatives aux paramètres du jeton personnalisé sont passées dans le webhook.
Afficher BIN et suffixe de carte	Les informations suivantes sur le numéro de la carte bancaire sont passées dans le webhook : les 6 premiers chiffres du paramètre card_bin ; les 4 derniers chiffres du card_suffix.
Afficher marque de carte	La marque de la carte utilisée pour effectuer le paiement. Par exemple, Mastercard ou Visa.

Tester les webhooks permet de s'assurer de la bonne configuration du projet, tant de votre côté que du côté de Xsolla.

Si les webhooks sont configurés avec succès, une section de test des webhooks s'affiche sous celle de configuration des webhooks.

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

Si vous recevez des webhooks combinés :

Nom de l'onglet pour le test du webhook	Nom et type du webhook
Payments and store	Validation utilisateur > Validation utilisateur (user_validation)
	Services de jeux > Webhooks combinés > Paiement de commande réussi (order_paid)
	Services de jeux > Webhooks combinés > Annulation de commande (order_canceled)
Subscriptions	Validation utilisateur > Validation utilisateur (user_validation)
	Payments > Paiement (payment)

Si vous recevez des webhooks distincts :

Nom de l'onglet pour le test du webhook	Nom et type du webhook
Store	Services de jeux > Webhooks distincts > Paiement de commande réussi (order_paid)
	Services de jeux > Webhooks distincts > Annulation de commande (order_canceled)
Payments	Validation utilisateur > Validation utilisateur (user_validation)
	Payments > Paiement (payment)
Subscriptions	Validation utilisateur > Validation utilisateur (user_validation)
	Payments > Paiement (payment)

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 d'objet. Si l'objet du type sélectionné n'est pas configuré dans le Compte éditeur, cliquez sur :

   • Connect — si le module contenant des objets de ce type n'est pas connecté ;
   • Configure — si vous avez connecté le module précédemment, mais n'avez pas encore terminé la configuration.
     En cliquant sur le bouton, vous serez redirigé vers la section correspondante du Compte éditeur selon le type d'objet sélectionné. Après avoir créé l'objet, revenez à la section de test des webhooks et passez à l'étape suivante.

3. Remplissez les champs nécessaires :

   1. Sélectionnez l'UGS du bien dans la liste déroulante et indiquez le montant. Pour choisir plusieurs biens du même type, cliquez sur + et ajoutez-les sur une nouvelle ligne  ;
   2. ID utilisateur — lors des tests, utilisez n'importe quelle combinaison de lettres et de chiffres.
   3. ID utilisateur public — ID connu de l'utilisateur, par exemple, une adresse e-mail ou un pseudo. Ce champ s'affiche si l'ID utilisateur public est activé dans votre projet dans Pay Station > Paramètres ;
   4. Entrez n'importe quelle valeur dans le champ ID de commande Xsolla ;
   5. ID de facture Xsolla — ID de la transaction côté Xsolla. Lors des tests, utilisez n'importe quelle valeur numérique ;
   6. ID de facture — ID de la transaction du côté de votre jeu. Lors des tests, utilisez n'importe quelle combinaison de lettres et de chiffres. Ce n'est pas un paramètre obligatoire pour un paiement réussi, mais vous pouvez le passer pour lier l'ID de la transaction de votre côté à l'ID de la transaction côté Xsolla ;
   7. Montant — montant du paiement. Lors des tests, utilisez n'importe quelle valeur numérique ;
   8. Devise — sélectionnez une devise dans la liste déroulante.

4. Cliquez sur Tester les webhooks.

Les webhooks Validation urilisateur, 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 le bouton Tester les webhooks.

Si l'ID utilisateur public est activé dans votre projet, les résultats de la vérification de la recherche utilisateur seront également visibles.

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.

Dans l'onglet Subscriptions, vous pouvez tester les webhooks suivants :

• Validation utilisateur (user_validation) ;
• Paiement (payment).

Pour tester :

1. Dans la section de test, accédez à l'onglet Subscriptions.
2. Remplissez les champs nécessaires :
   1. ID utilisateur — lors des tests, utilisez n'importe quelle combinaison de lettres et de chiffres ;
   2. ID de facture Xsolla — ID de transaction côté Xsolla. Lors des tests, utilisez n'importe quelle valeur numérique ;
   3. ID utilisateur public — ID connu de l'utilisateur, par exemple, une adresse e-mail ou un pseudo. Ce champ s'affiche si l'ID utilisateur public est activé dans votre projet dans la section Pay Station > Paramètres > Paramètres supplémentaires ;
   4. Devise — sélectionnez une devise dans la liste déroulante ;
   5. ID de plan — un plan d'abonnement. Choisissez un plan dans la liste déroulante ;
   6. Produit d'abonnement — choisissez un produit dans la liste déroulante (facultatif) ;
   7. Montant — montant du paiement. Lors des tests, utilisez n'importe quelle valeur numérique ;
   8. ID de facture — ID de transaction du côté de votre 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 passer pour lier l'ID de transaction de votre côté à l'ID de transaction côté Xsolla ;
   9. Période d'essai — pour tester l'acha t d'un abonnement sans période d'essai ou le renouvellement d'un abonnement, spécifiez la valeur 0.
3. Cliquez sur Tester les webhooks.

Vous recevrez des webhooks avec des données remplies à l'URL spécifiée. Les résultats des tests de chaque webhook, pour un scénario réussi et un scénario avec une erreur, sont affichés sous le bouton Test webhooks.

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.

Du côté de votre application, implémentez la réception de webhooks depuis les adresses IP suivantes : 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197.

Restrictions :

• La base de données de votre application ne doit pas contenir plusieurs transactions réussies avec le même ID.
• Si l'écouteur reçoit un webhook avec un ID qui existe déjà dans la base de données, renvoyez le résultat précédent du traitement de cette transaction. Il est déconseillé de créditer l'utilisateur pour un achat déjà effectué et de créer des enregistrements en double dans la base de données.

Lors de la réception d'un webhook, il est impératif de garantir la sécurité de la transmission des données. Pour ce faire, 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.

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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. Le gestionnaire de webhook peut également renvoyer un code HTTP 5xx en cas de problèmes temporaires sur votre serveur.

Si le serveur Xsolla n'a pas reçu 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 n'a pas reçu de réponse au webhook Paiement ou au webhook Remboursement, ou s'il a reçu une réponse contenant un code 5xx, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectués dans les 12 heures.

Si le serveur Xsolla n'a pas reçu de réponse au webhook Validation utilisateur ou s'il a reçu une réponse contenant un code 400 ou 5xx, le webhook Validation utilisateur n'est pas renvoyé. Dans ce cas, l'utilisateur voit une erreur et les webhooks Paiement et Paiement de commande réussi ne sont pas envoyés.

Codes d'erreur pour le code HTTP 400 :

Code	Message
INVALID_USER	Utilisateur non valide
INVALID_PARAMETER	Paramètre non valide
INVALID_SIGNATURE	Signature non valide
INCORRECT_AMOUNT	Montant incorrect
INCORRECT_INVOICE	Facture incorrecte

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook	Type de notification	Description
Validation utilisateur	user_validation	Envoyé pour vérifier si l'utilisateur existe dans le jeu.
Recherche utilisateur	user_search	Envoyé pour récupérer les informations sur l'utilisateur à partir de son ID utilisateur public.
Paiement	payment	Envoyé lorsque l'utilisateur effectue un paiement.
Remboursement	refund	Envoyé lorsqu'un paiement doit être annulé pour une raison quelconque.
Remboursement partiel	partial_refund	Envoyé lorsqu'un paiement doit être partiellement annulé pour une raison quelconque.
Transaction rejetée par AFS	afs_reject	Envoyé lorsqu'une transaction est refusée lors d'un contrôle AFS.
Mise à jour de la liste noire AFS	afs_black_list	Envoyé lorsque la liste noire AFS est mise à jour.
Abonnement créé	create_subscription	Envoyé lorsque l'utilisateur crée un abonnement.
Abonnement mis à jour	update_subscription	Envoyé lors du renouvellement ou de la modification d'un abonnement.
Abonnement annulé	cancel_subscription	Envoyé lorsqu'un abonnement est annulé.
Abonnement non renouvelable	non_renewal_subscription	Envoyé lorsque le statut est défini sur non renouvelable.
Ajout de compte de paiement	payment_account_add	Envoyé lorsque l'utilisateur ajoute ou enregistre un compte de paiement.
Suppression de compte de paiement	payment_account_remove	Envoyé lorsque l'utilisateur supprime un compte de paiement des comptes enregistrés.
Validation utilisateur dans Web Shop	-	Envoyé depuis le site d'un Web Shop pour vérifier si l'utilisateur existe dans le jeu.
Personnalisation du catalogue côté partenaire	partner_side_catalog	Envoyé lorsque l'utilisateur interagit avec le magasin.
Paiement de commande réussi	order_paid	Envoyé lorsqu'une commande est payée.
Annulation de commande	order_canceled	Envoyé lorsqu'une commande est annulée.
Contestation	dispute	Envoyé lorsqu'une nouvelle contestation est ouverte.