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 :

Paramètres des webhooks lors de votre travail avec les produits et solutions Xsolla :

Product/ 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.
Buy Button	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	Pour recevoir des informations sur la création, la mise à jour ou l'annulation d'abonnements. Vous pouvez également demander des informations via API.
Web Shop	Facultatif	Pour l'authentification utilisateur, si vous utilisez l'authentification par ID utilisateur. Vous pouvez également utiliser l'authentification utilisateur via Xsolla Login.
Digital Distribution Hub	Facultatif	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. Pour en savoir plus, consultez lesinstructions relatives à la configuration des webhooks pour Digital Distribution Hub.

Si vous utilisez des produits et des solutions nécessitant 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.

Pour exploiter pleinement l'In-Game Store, il est essentiel d'implémenter et de traiter les 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.
• Paiement de commande réussi (order_paid) — envoyé lorsqu'un webhook Paiement est traité avec succès et contient des informations sur les objets achetés ainsi que l'ID de la transaction. Utilisez ces données pour octroyer les objets à l'utilisateur.
• 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.
• Annulation de commande (order_canceled) — envoyé lorsqu'un webhook Remboursement est traité avec succès et contient des informations sur les objets achetés ainsi que l'ID de la transaction annulée. Utilisez ces données 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. Ouvrez votre projet dans le Compte éditeur.
2. Cliquez sur Project settings dans le menu latéral et accédez à l'onglet Webhooks.
3. 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.
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.

Pour désactiver la réception de webhooks :

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

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

Vous pouvez tester la réception des webhooks suivants :

Nom du webhook	Type de webhook
Validation utilisateur	user_validation
Paiement	payment
Annulation de commande	order_canceled
Paiement de commande réussi	order_paid

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

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

• 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 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. Entrez une valeur aléatoire dans le champ Xsolla Order ID.
4. Sélectionnez l'UGS de l'objet dans la liste déroulante et indiquez le montant. Pour choisir plusieurs objets du même type, cliquez sur + et ajoutez-les sur une nouvelle ligne.
5. Choisissez la devise dans laquelle la commande sera payée.
6. Cliquez sur Test.

Les webhooks 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 Test webhooks.

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

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

Pour tester :

1. Dans la section de test, accédez à l'onglet Payments.
2. Remplissez les champs nécessaires :

   1. User ID — lors des tests, utilisez n'importe quelle combinaison de lettres et de chiffres ;
   2. Public user ID — 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 > Settings > Additional settings ;
   3. Currency — sélectionnez une devise dans la liste déroulante ;
   4. Xsolla Invoice ID — ID de transaction côté Xsolla. Lors des tests, utilisez n'importe quelle valeur numérique ;
   5. Amount — montant du paiement. Lors des tests, utilisez n'importe quelle valeur numérique ;
   6. Invoice ID — 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 transmettre pour lier l'ID de transaction de votre côté à l'ID de transaction côté Xsolla.
3. Cliquez sur Test 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. 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.

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.

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.

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. User ID — lors des tests, utilisez n'importe quelle combinaison de lettres et de chiffres ;
   2. Xsolla Invoice ID — ID de transaction côté Xsolla. Lors des tests, utilisez n'importe quelle valeur numérique ;
   3. Public user ID — 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 > Settings > Additional settings ;
   4. Currency — sélectionnez une devise dans la liste déroulante ;
   5. Plan ID — un plan d'abonnement. Choisissez un plan dans la liste déroulante ;
   6. Subscription product — choisissez un produit dans la liste déroulante (facultatif) ;
   7. Amount — montant du paiement. Lors des tests, utilisez n'importe quelle valeur numérique ;
   8. Invoice ID — 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. Trial period — 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 Test 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.

Au cas où aucune réponse n'est reçue pour les webhooks Paiement de commande réussi et Annulation de commande, ou si une réponse contenant un code 5xx est reçue, 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 aucune réponse n'a été reçue pour les webhooks Paiement ou Remboursement, ou si une réponse contenant un code 5xx est reçue, les webhooks sont également renvoyés à intervalles de temps croissants. Un maximum de 12 tentatives sont effectuées dans les 12 heures.

Si aucune réponse n'est reçue pour le webhook Validation utilisateur, ou si une réponse avec un code 400 ou 5xx est reçue, le webhook Validation utilisateur n'est pas renvoyé. Dans ce cas, une erreur est signalée à l'utilisateur, 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.