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 exploiter pleinement In-Game Store, il est nécessaire d’implémenter le traitement des principaux webhooks :

  • Paiement — est envoyé lorsqu’une commande est payée, et contient les informations sur le paiement et les détails de la transaction.
  • Paiement de commande réussi — est envoyé lorsqu’un webhook Paiement a été traité avec succès, et contient les informations sur les objets achetés et l’ID de transaction. Utilisez les données du webhook pour octroyer les objets à l’utilisateur.
  • Remboursement — est envoyé lorsqu’une commande est annulée, et contient les informations sur le paiement annulé et les détails de la transaction.
  • Annulation de commande — est envoyé lorsqu’un webhook Remboursement a été traité avec succès, et contient les informations sur les objets achetés et l’ID de la transaction annulée. Utilisez les données du webhook pour supprimer les objets achetés.
  • Validation utilisateur — est envoyé à différentes étapes du paiement pour s’assurer que l’utilisateur est bel et bien enregistré dans le jeu.

Vous trouverez ci-dessous un schéma illustrant le processus d’achat et de retour de produits sur le site Web en utilisant les webhooks de cette liste.

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.

Note
Pour recevoir les paiements réels, il vous suffit d’implémenter le traitement des webhooks Paiement, Paiement de commande réussi, et Validation utilisateur, ainsi que de signer le contrat de licence.
Note
Vous pouvez utiliser l’intégration de PlayFab pour recevoir les informations de paiement et d’annulation de commande au lieu d’utiliser les webhooks.

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.

Avis
Le protocole HTTPS est utilisé pour transférer les données ; le protocole HTTP n’est pas pris en charge.
  1. 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.
  2. Cliquez sur Enable webhooks.
Note
Pour tester les webhooks, vous pouvez choisir n’importe quel site dédié, tel que webhook.site, ou une plateforme, telle que ngrok.
Avis
Il est impossible d’envoyer simultanément des webhooks à différentes URL. Une approche consiste à spécifier d’abord une URL pour les tests dans le Compte éditeur, puis à la remplacer par l’URL réelle.
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

Vous pouvez tester la réception des webhooks suivants :

Nom du webhookType de webhook
User validationuser_validation
Paymentpayment
Annulation de commandeorder_canceled
Successful payment of the orderorder_paid

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

É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 aucune réponse n’a été reçue pour les webhooks Successful payment of the order et Order cancellation ou si une réponse contenant un code 5xx a été 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 le webhook Payment ou si une réponse contenant un code 5xx a été 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’a été reçue pour le webhook User validation ou si une réponse contenant un code 400 ou 5xx a été reçue, le webhook User validation 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.

Note
La liste complète et le mécanisme des webhooks, ainsi que des exemples détaillés de leur traitement, sont décrits dans la documentation webhooks.
Cet article vous a été utile ?
Merci !
Que pouvons-nous améliorer ? Message
Nous sommes désolés de l'apprendre
Dites-nous pourquoi vous n'avez pas trouvé cet article utile. Message
Merci pour votre commentaire !
Nous examinerons votre message et l'utiliserons pour améliorer votre expérience.
Dernière mise à jour: 11 Septembre 2024

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.

Signaler un problème
Nous améliorons continuellement notre contenu grâce à vos commentaires.
Indiquez votre adresse e-mail pour un suivi
Merci pour votre commentaire !