Les webhooks vous permettent de recevoir des notifications instantanées des événements configurés qui se produisent côté Xsolla. Vous pouvez utiliser des webhooks pour automatiser le back-end et d'autres fonctions de votre application.

Exemples d'événements pouvant être notifiés :

• paiements, y compris les achats de monnaie virtuelle et d'objets ;
• paiements récurrents et actions liées aux abonnements ;
• remboursements.

Lorsqu'un événement configuré se produit, Xsolla en notifie à votre système via des webhooks. À titre d'exemple, les opérations ci-dessous peuvent être effectuées après réception d'un webhook :

• ajouter au solde utilisateur ;
• débloquer de nouveaux objets pour un utilisateur ;
• démarrer le service d'abonnement ;
• bloquer l'utilisateur après détection de fraude.

Exemple de fonctionnement d'un webhook de traitement des paiements :

Les paramètres suivants doivent être appliqués pour que les webhooks fonctionnent correctement :

• Écoute des webhooks aux adresses IP suivantes : 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
• La base de données de l'application ne doit pas contenir deux transactions réussies portant le même ID.

• Une signature créée doit correspondre à celle transmise dans l'en-tête HTTP.
• En cas d'erreur, renvoyez le code 400(par exemple, lorsqu'un paramètre requis est manquant ou qu'un ajout au solde a échoué). Pour les erreurs temporaires sur vos serveurs, utilisez le code 500.

Comme les connexions Internet ne sont pas toujours fiables à 100 %, il est possible que les webhooks se perdent ou soient retardés. Pour résoudre ce problème, Xsolla renvoie les webhooks qui ont échoué jusqu'à ce que votre écouteur les reçoive. Les tentatives de renvoi sont effectuées dans les 12  heures suivant la première tentative. Le nombre maximal de tentatives de renvoi est de 12.

Les signatures numériques permettent de sécuriser la transmission des données. Pour générer une signature, procédez comme suit :

1. Concaténez le corps JSON de la requête avec la clé secrète de votre projet.
2. Appliquez le hachage SHA-1 à la chaîne résultante.

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"
      }
    }'

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"
    }
}