Überblick

Webhooks ermöglichen es Ihnen, Sofortbenachrichtigungen über konfigurierte Ereignisse zu erhalten, die aufseiten von Xsolla eintreten. Mithilfe von Webhooks können Sie Back-End- und Zusatzfunktionen Ihrer Anwendung automatisieren.

Beispielhafte Ereignisse, über die Sie benachrichtigt werden können:

Zahlungen, einschließlich Käufe von virtueller Währung und virtuellen Gegenständen
wiederkehrende Zahlungen und Aktionen im Zusammenhang mit Abonnements
Erstattungen

Wenn ein konfiguriertes Ereignis eintritt, benachrichtigt Xsolla Ihr System per Webhooks darüber. Beispielsweise können Sie nach dem Erhalt eines Webhooks folgendes in die Wege leiten:

dem Benutzerkonto Guthaben gutschreiben
neue Gegenstände für einen Benutzer freischalten
Abonnementdienst starten
Benutzer nach Betrugserkennung sperren

Anhand des folgenden Beispiels wird erläutert, wie ein für die Zahlungsabwicklung zuständiger Webhook funktioniert:

Webhook für die
Zahlungsabwicklung

Serverseitig einrichten

Damit Webhooks korrekt funktionieren, müssen folgende Einstellungen vorgenommen werden:

Webhooks können über folgende IP-Adressen empfangen werden: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
Die Anwendungsdatenbank darf nicht zwei erfolgreiche Transaktionen mit derselben ID enthalten.

Hinweis

Wenn Ihr Listener einen Webhook mit einer bereits vorhandenen Transaktions-ID empfängt, muss er das vorherige Ergebnis für diese Transaktion zurückgeben. Es wird nicht empfohlen, dem Benutzer etwas doppelt zu berechnen oder doppelte Einträge in der Datenbank zu erstellen.

Eine erstellte Signatur muss mit der im HTTP-Header übermittelten übereinstimmen.
Im Falle eines Fehlers ist der Code 400 zurückzugeben (z. B. wenn ein erforderlicher Parameter fehlt oder eine Aufladung fehlgeschlagen ist). Verwenden Sie bei vorübergehender Störung Ihrer Server den Code 500.

Hinweis

Die Xsolla-API akzeptiert klassische HTTP-Antwortcodes bei erfolgreichen und fehlgeschlagenen Anfragen. Code 204 signalisiert eine erfolgreiche Verarbeitung.

Da Internetverbindungen nicht immer 100 % zuverlässig sind, können Webhooks verloren gehen oder sich verzögern. Um dieses Problem zu lösen, sendet Xsolla fehlgeschlagene Webhooks erneut, bis Ihr Listener sie empfängt. Webhooks werden innerhalb von 12 Stunden nach dem Versand des vorherigen erneut gesendet, bis Ihr Listener den Empfang bestätigt. Maximal sind 12 Versuche möglich.

Hinweis

Obwohl Verbindungsprobleme dazu führen können, dass Webhooks verloren gehen, sich verzögern oder doppelt gesendet werden, ist die häufigste Ursache eine fehlerhafte Logik aufseiten des Listener.

Signaturanfragen

Digitale Signaturen ermöglichen eine sichere Datenübertragung. So generieren Sie eine Signatur:

Verketten Sie den JSON-Body der Anfrage mit dem geheimen Schlüssel Ihres Projekts.
Wenden Sie den SHA-1-Algorithmus auf den resultierenden String an.

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

Fehler

Fehlercodes für den HTTP-Code 400:

Code	Nachricht
INVALID_USER	Ungültiger Benutzer
INVALID_PARAMETER	Ungültiger Parameter
INVALID_SIGNATURE	Unzulässige Signatur
INCORRECT_AMOUNT	Ungültiger Betrag
INCORRECT_INVOICE	Ungültige Rechnung

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