Xsolla-logo

Ü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:

  1. Verketten Sie den JSON-Body der Anfrage mit dem geheimen Schlüssel Ihres Projekts.
  2. 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"
    }
}

Liste der Webhooks

Hinweis

Der Benachrichtigungstyp wird im Parameter notification_type gesendet.

Webhook Produkt/Lösung Benachrichtigungstyp Beschreibung
Benutzervalidierung Bezahlstation user_validation Wird versendet, um zu prüfen, ob ein Benutzer im Spiel existiert.
Benutzersuche Bezahlstation user_search Wird versendet, um Benutzerinformationen anhand der öffentlichen Benutzer-ID abzurufen.
Zahlung Bezahlstation, Abonnements payment Wird versendet, wenn ein Benutzer eine Zahlung abschließt.
Erstattung Bezahlstation, Abonnements refund Wird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
Teilerstattung Bezahlstation partial_refund Wird versendet, falls eine Zahlung aus einem beliebigen Grund teilweise storniert werden muss.
Abgelehnte Transaktion (AFS) Bezahlstation afs_reject Wird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird.
Aktualisierte AFS-Blockliste Bezahlstation afs_black_list Wird bei Aktualisierung der AFS-Blockliste versendet.
Abgeschlossenes Abonnement Abonnements create_subscription Wird versendet, wenn ein Benutzer ein Abonnement abschließt.
Aktualisiertes Abonnement Abonnements update_subscription Wird versendet, wenn ein Abonnement erneuert oder geändert wird.
Storniertes Abonnement Abonnements cancel_subscription Wird versendet, wenn ein Abonnement gekündigt wird.
Automatisch endendes Abonnement Abonnements non_renewal_subscription Wird versendet, wenn der Status auf "Automatisch endend" gesetzt wird.
Spielschlüssel abrufen Buy Button get_pincode Wird versendet, wenn die Xsolla-API den Spielschlüssel abrufen möchte.
Benutzerguthaben: Manuelle Aktualisierung Ingame-Online-Shop user_balance_operation Wird versendet, wenn sich ein Benutzerguthaben manuell ändert. Operationstyp: internal.
Benutzerguthaben: Zahlung Ingame-Online-Shop user_balance_operation Wird versendet, wenn ein Benutzer eine Zahlung vornimmt. Operationstyp:payment.
Benutzerguthaben: Erstattung Ingame-Online-Shop user_balance_operation Wird versendet, wenn ein Benutzer die Zahlung storniert. Operationstyp: cancellation.
Benutzerguthaben: Gutschein einlösen Ingame-Online-Shop user_balance_operation Wird versendet, wenn ein Benutzer einen Gutschein einlöst, um virtuelle Gegenstände oder virtuelle Währung in einem Spiel zu erhalten. Operationstyp: coupon.
Benutzerguthaben: Kauf Ingame-Online-Shop user_balance_operation Wird versendet, wenn ein Benutzer in einem Spiel etwas kauft. Operationstyp: inGamePurchase.
Freunde abrufen Buy Button friends_list Wird versendet, wenn ein Benutzer seine Freundesliste abfragt.
Schlüssel aktivieren Buy Button redeem_key Wird versendet, wenn ein Benutzer einen Schlüssel aktiviert.
Upgrade-Erstattung Buy Button upgrade_refund Wird bei Stornierung des Upgrades versendet.
Zahlungskonto hinzufügen Bezahlstation payment_account_add Wird versendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert.
Zahlungskonto entfernen Bezahlstation payment_account_remove Wird versendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt.
Benutzervalidierung im Webshop Webshop - Wird von einer Webshop-Seite gesendet, um zu prüfen, ob ein Benutzer im Spiel vorhanden ist.
Abschluss der Auszahlungstransaktion Auszahlungen - Wird gesendet, um mitzuteilen, dass die Auszahlungstransaktion erfolgreich abgeschlossen wurde.
Katalogpersonalisierung aufseiten des Partners Ingame-Online-Shop partner_side_catalog Wird gesendet, wenn ein Benutzer mit dem Shop interagiert.