Xsolla-logo

Überblick

Webhooks sind Benachrichtigungen über Ereignisse im System. Wenn ein bestimmtes Ereignis eintritt, sendet Xsolla eine HTTP-Anfrage mitsamt den Ereignisdaten an Ihre Anwendung. In der Regel handelt es sich dabei um eine POST-Anfrage im JSON- Format.

Ereignisbeispiele:

  • Nutzer interagiert mit einem Artikelkatalog
  • Bestellung wird bezahlt oder storniert

Wenn ein bestimmtes Ereignis eintritt, benachrichtigt Xsolla Ihr System per Webhook. Infolgedessen können Sie Aktionen einleiten, wie zum Beispiel:

  • das Guthaben eines Nutzers aufladen
  • eine Zahlung erstatten
  • dem Nutzerkonto neue Artikel gewähren oder Artikel aus dem Nutzerkonto entfernen
  • ein Abonnement aktivieren
  • einen Nutzer bei Betrugsverdacht sperren

Beispielhafter Webhook-Ablauf bei der Zahlungsabwicklung:

Webhook für die 
Zahlungsabwicklung

Videoanleitung für die Xsolla-Webhook-Integration:

Webhooks-Einstellungen beim Arbeiten mit Xsolla-Produkten und ‑Lösungen:

Produkt/Lösung Erforderlich/Optional Wozu die Webhooks verwendet werden
Payments Erforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
In-Game Store Erforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
Game Sales Optional Für den Verkauf von Spielschlüsseln sind keine Benutzervalidierung und keine Gewährung von Artikeln erforderlich. Dennoch können Sie Webhooks nutzen, wenn Sie Informationen über Ereignisse erhalten möchten, z. B., wenn eine Bestellung bezahlt oder storniert wird.
Wenn Sie sich für Webhooks entscheiden, ist es wichtig, alle eingehenden erforderlichen Webhooks zu verarbeiten.
Subscriptions Optional Zum Abrufen von Informationen über den Abschluss, die Aktualisierung oder die Kündigung eines Abonnements. Alternativ können Sie die Informationen auch über die API anfordern.
Web Shop Erforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
  • Für die Benutzerauthentifizierung, wenn Sie Benutzer über deren ID authentifizieren. Alternativ dazu können Sie Benutzer über Xsolla Login authentifizieren.
Digital Distribution Hub Erforderlich
  • Benutzervalidierung.
  • Transaktions-ID aufseiten von Xsolla mit der Transaktions-ID in Ihrem System verknüpfen
  • zusätzliche Transaktionsparameter in der Bestellung übermitteln
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen

Ausführliche Informationen zum Einrichten von Webhooks für den Digital Distribution Hub finden Sie in der Dokumentation.

Liste der erforderlichen Webhooks

Wenn Sie Produkte und Lösungen verwenden, die Webhooks erfordern, müssen Sie die Webhooks in Ihrem Kundenportal aktivieren, testen und deren Verarbeitung einrichten. Wenn bestimmte Ereignisse eintreten, werden die Webhooks der Reihe nach gesendet. Wenn Sie also einen der Webhooks nicht verarbeiten, werden die nachfolgenden Webhooks nicht gesendet. Die Liste der erforderlichen Webhooks finden Sie unten.

In-Game Store und Payments

Für den Kauf und die Rückgabe von Artikeln auf der Website hat Xsolla zwei Webhook-Sendeoptionen eingerichtet: Informationen über Zahlungs- und Transaktionsdaten sowie Informationen über gekaufte Artikeln können entweder separat oder zusammengefasst in einem Webhook gesendet werden.

Empfang von Informationen in kombinierten Webhooks:

Wenn Sie sich nach dem 22. Januar 2025 im Kundenportal registriert haben, werden alle Informationen in den Webhooks Erfolgreiche Bezahlung der Bestellung (order_paid) und Stornierung der Bestellung (order_canceled) übermittelt. In diesem Fall müssen Sie die Webhooks Zahlung (payment) und Erstattung (refund) nicht verarbeiten.

Empfang von Informationen in separaten Webhooks:

Wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben, empfangen Sie die folgenden Webhooks:

Sie müssen alle eingehenden Webhooks verarbeiten. Wenn Sie auf die neue Option (Empfang kombinierter Webhooks) umsteigen möchten, wenden Sie sich an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.

Damit In-Game Store und die Zahlungsverwaltung uneingeschränkt funktionieren, muss die Verarbeitung der wichtigsten Webhooks implementiert sein.

Beim Empfang kombinierter Webhooks:

Webhook-Name und ‑Typ Beschreibung
Benutzervalidierung > Benutzervalidierung (user_validation) Wird in verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
Spieldienste > kombinierte Webhooks > Erfolgreiche Bezahlung der Bestellung (order_paid) Enthält Zahlungsdaten, Transaktionsdetails und Informationen über gekaufte Artikel. Verwenden Sie die Daten aus dem Webhook, um dem Nutzer Artikel zu gewähren.
Spieldienste > kombinierte Webhooks > Stornierung der Bestellung (order_canceled) Enthält Daten der stornierten Zahlung, Transaktionsdetails und Informationen über die gekauften Artikel. Verwenden Sie die Daten aus dem Webhook, um die gekauften Artikel zu entfernen.

Beim Empfang separater Webhooks:

Webhook-Name und ‑Typ Beschreibung
Benutzervalidierung > Benutzervalidierung (user_validation) Wird in verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
Zahlungen > Zahlung (payment) Enthält Zahlungsdaten und Transaktionsdetails.
Spieldienste > separate Webhooks > Erfolgreiche Bezahlung der Bestellung (order_paid) Enthält Informationen über gekaufte Artikel. Verwenden Sie die Daten aus dem Webhook, um dem Nutzer Artikel hinzuzufügen.
Zahlungen > Erstattung (refund) Enthält Zahlungsdaten und Transaktionsdetails.
Spieldienste > separate Webhooks > Stornierung der Bestellung (order_canceled) Enthält Informationen über die gekauften Artikel und die ID der stornierten Transaktion. Verwenden Sie die Daten aus dem Webhook, um die gekauften Artikel zu entfernen.

Falls die Artikelkatalogpersonalisierung aufseiten Ihrer Anwendung implementiert ist, müssen Sie den Webhook Katalogpersonalisierung aufseiten des Partners einrichten.

Hinweis

Um echte Zahlungen entgegennehmen zu können, müssen Sie lediglich die Lizenzvereinbarung unterzeichnen und die Verarbeitung der folgenden Webhooks implementieren:

Subscriptions

Um Abo-Modelle automatisch zu verwalten, muss die Verarbeitung der wichtigsten Webhooks implementiert sein:

  • Benutzervalidierung (user_validation) – wird in verschiedenen Phasen des Bezahlvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
  • Zahlung (payment) – wird gesendet, wenn eine Bestellung bezahlt wird, und enthält Zahlungsdaten sowie Transaktionsdetails.
  • Abgeschlossenes Abonnement (create_subscription) – wird gesendet, wenn ein Webhook vom Typ Zahlung erfolgreich verarbeitet wurde oder der Nutzer ein Probeabo abgeschlossen hat. Der Webhook enthält Details über das abgeschlossene Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um das Abonnement für den Nutzer zu aktivieren.
  • Aktualisiertes Abonnement (update_subscription) – wird gesendet, wenn ein Abonnement verlängert oder geändert und Webhook vom Typ Zahlung erfolgreich verarbeitet wurde. Der Webhook enthält Details über das abgeschlossene Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um das Abonnement des Nutzers zu verlängern oder die Abonnementparameter zu ändern.
  • Erstattung (refund) – wird gesendet, wenn eine Bestellung storniert wird und enthält die Daten der stornierten Zahlung sowie Transaktionsdetails.
  • Gekündigtes Abonnement (cancel_subscription) – wird gesendet, wenn ein Webhook vom Typ Erstattung erfolgreich verarbeitet oder das Abonnement aus einem anderen Grund gekündigt wurde. Der Webhook enthält Informationen über das Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um die vom Nutzer abgeschlossenen Abonnements zu kündigen.

Webhooks im Kundenportal einrichten

Allgemeine Einstellungen

So aktivieren Sie den Empfang von Webhooks:

  1. Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
  2. Geben Sie im Feld Webhook-Server die URL Ihres Servers an, auf dem Sie Webhooks im Format https://example.com empfangen möchten. Sie können auch eine URL aus einem Tool, mit dem sich Webhooks testen lassen, angeben.

Hinweis:

Für die Datenübertragung wird das HTTPS-Protokoll verwendet; das HTTP-Protokoll wird nicht unterstützt.

  1. Standardmäßig wird ein geheimer Schlüssel zum Signieren von Projekt-Webhooks generiert. Wenn Sie einen neuen geheimen Schlüssel generieren möchten, klicken Sie auf das Aktualisieren-Symbol.
  2. Klicken Sie auf Webhooks aktiveren.

Hinweis

Webhooks können Sie auch über eine beliebige zweckbestimmte Website (z. B. webhook.site) oder Plattform (z. B. ngrok) testen.

Hinweis

Sie können Webhooks nicht gleichzeitig an verschiedene URLs senden. Im Kundenportal können Sie jedoch zunächst eine URL zum Testen angeben und diese dann durch die echte URL ersetzen.

So deaktivieren Sie den Empfang von Webhooks:

  1. Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
  2. Klicken Sie auf Webhooks deaktivieren.

Erweiterte Einstellungen

Für die Webhooks im Abschnitt Payments und Store sind erweiterte Einstellungen verfügbar. Diese werden automatisch unter dem Block Allgemeine Einstellungen angezeigt, nachdem Sie auf die Schaltfläche Webhooks abrufen geklickt haben.

Hinweis

Wenn die erweiterten Einstellungen nicht angezeigt werden, müssen Sie zuerst den Webhook-Empfang in den allgemeinen Einstellungen aktivieren und dann zur Registerkarte Testen > Payments und Store wechseln.

Hier können Sie den Empfang zusätzlicher Informationen in Webhooks einrichten. Dazu müssen Sie die entsprechenden Schalter aktivieren. In jeder Berechtigungszeile werden die Webhooks angezeigt, die von der Änderung der Einstellungen betroffen sind.

Schalter Beschreibung
Infos über das gespeicherte Zahlungskonto anzeigen Informationen über die gespeicherte Zahlungsmethode werden in dem benutzerdefinierten Objekt payment_account übermittelt.
Infos über Transaktionen anzeigen, die mit gespeicherten Zahlungsmethoden getätigt wurden

Informationen werden in den folgenden benutzerdefinierten Parametern des Webhooks übermittelt.

  • saved_payment_method:
    • 0 – die gespeicherte Zahlungsmethode wurde nicht verwendet
    • 1 – die Zahlungsmethode wurde während des aktuellen Bezahlvorgangs gespeichert
    • 2 – die zuvor gespeicherte Zahlungsmethode wird verwendet
  • payment_type:
    • 1 – Einmalzahlung
    • 2 – wiederkehrende Zahlung
Bestellobjekt dem Webhook hinzufügen Die Informationen über die Bestellung werden im order-Objekt des Zahlung-Webhooks übermittelt.
Nur notwendige Nutzerparameter ohne vertrauliche Daten senden

Im Webhook werden nur die folgenden Nutzerinformationen übermittelt:

  • ID
  • Land
Individuelle Parameter senden Informationen über individuelle Tokenparameter werden in dem Webhook übermittelt.
BLZ und Endziffern von Karten anzeigen

Im Webhook werden nur die folgenden Informationen über die Bankkartennummer übermittelt:

  • die ersten sechs Ziffern im Parameter card_bin
  • die letzten vier Ziffern im Parameter card_suffix
Kartenmarke anzeigen Die Marke der Karte, mit der die Zahlung getätigt wurde. Zum Beispiel: Mastercard oder Visa.

Erweiterte 
Einstellungen

Webhooks im Kundenportal testen

Webhooks zu testen, hilft dabei, sicherzustellen, dass das Projekt sowohl bei Ihnen als auch aufseiten von Xsolla korrekt eingerichtet ist.

Sind die Webhooks erfolgreich eingerichtet, wird unterhalb des Einrichtungsbereichs ein Bereich zum Testen von Webhooks angezeigt.

Webhook-
Testbereich

Der Testbereich im Kundenportal variiert je nach dem, welche Webhook- Empfangsoption ausgewählt sind.

Beim Empfang kombinierter Webhooks:

Registerkartenname für Webhook-Tests Webhook-Name und ‑Typ
Payments und Store Benutzervalidierung > Benutzervalidierung (user_validation)
Spieldienste > kombinierte Webhooks > Erfolgreiche Bezahlung der Bestellung (order_paid)
Spieldienste > kombinierte Webhooks > Stornierung der Bestellung (order_canceled)
Subscriptions Benutzervalidierung > Benutzervalidierung (user_validation)
Zahlungen > Zahlung (payment)

Beim Empfang separater Webhooks:

Registerkartenname für Webhook-Tests Webhook-Name und ‑Typ
Store Spieldienste > separate Webhooks > Erfolgreiche Bezahlung der Bestellung (order_paid)
Spieldienste > separate Webhooks > Stornierung der Bestellung (order_canceled)
Payments Benutzervalidierung > Benutzervalidierung (user_validation)
Zahlungen > Zahlung (payment)
Subscriptions Benutzervalidierung > Benutzervalidierung (user_validation)
Zahlungen > Zahlung (payment)

Hinweis

Wird im Testbereich eine Fehlermeldung angezeigt, wonach der Test nicht erfolgreich war, sollten Sie in den Einstellungen Ihres Webhook-Listener prüfen, wie dieser auf Webhooks antwortet. Die Gründe für den fehlgeschlagenen Test sind in den Testergebnissen ersichtlich.

Beispiel:

Sie haben eine spezielle Website (z. B. webhook.site) zum Testen verwendet.

Im Abschnitt Test: Antwort auf eine ungültige Signatur wird ein Fehler angezeigt.

Das liegt daran, dass Xsolla einen Webhook mit falscher Signatur gesendet hat und nun erwartet, dass Ihr Handler mit dem HTTP-Statuscode 4xx und dem Fehlercode INVALID_SIGNATURE antwortet.

webhook.site antwortet allen Webhooks mit dem HTTP-Statuscode 200, selbst solchen Webhooks mit ungültiger Signatur. Weil der HTTP-Statuscode 4xx nicht wie erwartet empfangen wurde, ist das Testergebnis fehlerhaft.

Testfehler

Im Folgenden ist der Testvorgang für das Szenario mit kombinierten Webhooks beschrieben.

Payments und Store

Auf der Registerkarte Payments und Store können Sie die folgenden Webhooks testen:

So testen Sie die Webhooks:

  1. Wechseln Sie im Webhooks-Testbereich zur Registerkarte Payments und Store.

  2. Wählen Sie im Drop-down-Menü einen Artikeltyp aus. Ist der ausgewählte Artikeltyp im Kundenportal nicht eingerichtet, klicken Sie auf:

    • Verknüpfen, sofern das entsprechende Modul noch nicht verknüpft ist,
    • Konfigurieren, sofern das Modul bereits verknüpft, aber die Einrichtung noch nicht abgeschlossen ist.
      Durch Klick auf die Schaltfläche werden Sie zum entsprechenden Abschnitt im Kundenportal weitergeleitet. Nachdem Sie den Artikel angelegt haben, sollten Sie zum Webhook-Testbereich zurückkehren und mit dem nächsten Schritt fortfahren.
  3. Füllen Sie die Pflichtfelder aus:

    1. Wählen Sie die SKU des Artikels aus der der Drop-down-Liste aus, und legen Sie die Menge fest. Sie können mehrere Artikel desselben Typs wählen, indem Sie auf + klicken und einen weiteren Artikel in der neuen Zeile hinzufügen.
    2. Benutzer- ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
    3. Public-User-ID – ID, die dem Nutzer bekannt ist, z. B. E-Mail-Adresse oder Nickname. Dieses Feld wird angezeigt, sofern die Public-User-ID in Ihrem Projekt unter Pay Station > Einstellungen aktiviert ist.
    4. Geben Sie einen beliebigen Wert in das Feld Xsolla- Bestell-ID ein.
    5. Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    6. Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben. Dieser Parameter ist für eine erfolgreiche Zahlung nicht erforderlich. Allerdings können Sie die Transaktions-ID aufseiten Ihres Spiels mit der Transaktions-ID aufseiten von Xsolla verknüpfen, indem Sie den Parameter übermitteln.
    7. Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    8. Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.

  4. Klicken Sie auf Webhooks testen.

Die Webhooks Benutzervalidierung, Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung werden zusammen mit den angegebenen Daten an die festgelegte URL gesendet. Die Testergebnisse der einzelnen Webhook-Typen werden unter der Schaltfläche Webhooks testen angezeigt.

Wenn in Ihrem Projekt die Public-User-ID aktiviert ist, werden ebenso die Ergebnisse einer Benutzerprüfung angezeigt.

Für jeden Webhook müssen Sie die Verarbeitung beider Szenarien, also erfolgreich und fehlerbehaftet, konfigurieren.

Abschnitt zum Testen von 
Zahlungen

Subscriptions

Auf der Registerkarte Subscriptions können Sie die folgenden Webhooks testen:

Hinweis

Im Kundenportal können Sie nur die grundlegenden Webhooks vom Typ "Benutzervalidierung" und "Zahlung" testen. Wie Sie andere Webhook-Typen testen, erfahren Sie unter:

Hinweis

Damit Sie Webhooks testen können, müssen Sie unter Kundenportal > Subscriptions > Abo-Modelle mindestens eine Abo-Modell erstellt haben.

So testen Sie die Webhooks:

  1. Wechseln Sie im Testbereich zur Registerkarte Subscriptions.
  2. Füllen Sie die Pflichtfelder aus:

    1. Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
    2. Xsolla-Rechnungs- ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    3. Public- User-ID – ID, die einem Nutzer bekannt ist, z. B. E-Mail-Adresse oder Nickname. Dieses Feld wird angezeigt, sofern die Public-User-ID in Ihrem Projekt unter Pay Station > Einstellungen > Sonstige Einstellungen aktiviert ist.
    4. Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
    5. ID des Abo-Modells – Abo-Modell. Wählen Sie ein Abo-Modell aus der Drop-down-Liste.
    6. Abo-Produkt – Wählen Sie ein Produkt aus der Drop-down-Liste (optional).
    7. Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    8. Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben. Dieser Parameter ist nicht erforderlich, um die Zahlung erfolgreich zu verarbeiten. Allerdings können Sie die Transaktions-ID aufseiten Ihres Spiels mit der Transaktions-ID aufseiten von Xsolla verknüpfen, indem Sie den Parameter übermitteln.
    9. Probezeitraum. Wenn Sie den Absc hluss eines Abonnements ohne Probezeitraum oder die Verlängerung eines Abonnements testen möchten, geben Sie den Wert 0 an.
  3. Klicken Sie auf Webhooks testen.

Unter der angegebenen URL erhalten Sie Webhooks mit ausgefüllten Daten. Die Testergebnisse jedes Webhooks, sowohl für ein erfolgreiches Szenario als auch für ein Fehlerszenario, werden unter der Schaltfläche Webhooks testen angezeigt.

Webhook-Listener

Ein Webhook-Listener ist ein Programmcode, der es ermöglicht, eingehende Webhooks unter einer bestimmten URL-Adresse zu empfangen, eine Signatur zu generieren und dem Xsolla-Webhook-Server zu antworten.

Hinweis

Sie können die Pay Station PHP SDK-Bibliothek verwenden, die vorgefertigte Klassen für die Verarbeitung von Webhooks enthält.

Implementieren Sie aufseiten Ihrer Anwendung, dass Webhooks von den folgenden IP-Adressen empfangen werden können: 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.

Einschränkungen:

  • In der Datenbank Ihrer Anwendung dürfen nicht mehrere erfolgreiche Transaktionen mit derselben ID vorhanden sein.
  • Wenn der Webhook-Listener einen Webhook mit einer ID empfängt, die bereits in der Datenbank vorhanden ist, muss das Ergebnis der zuvor verarbeiteten Transaktion zurückgeben werden. Es wird davon abgeraten, dem Nutzer einen gekauften Artikel zweimal zu gewähren und doppelte Datensätze in der Datenbank anzulegen.

Signatur generieren

Während des Empfangs eines Webhooks sollten Sie die Sicherheit der Datenübertragung gewährleisten. Dazu muss aus den Webhook-Daten eine Signatur generiert und gegen die Signatur im HTTP-Anfrage-Header abgeglichen werden. So generieren Sie eine Signatur:

  1. Verketten Sie das JSON aus dem Anfragerumpf mit dem geheimen Schlüssel des Projekts.
  2. Wenden Sie die kryptografische Hash-Algorithmus SHA-1 auf den im ersten Schritt erhaltenen 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"
      }
    }'

Dem Webhook antworten

Ihr Server muss wie folgt antworten, um den Empfang eines Webhooks zu bestätigen:

  • mit dem HTTP-Statuscode 200, 201 oder 204 ohne Nachrichtenrumpf im Falle einer positiven Antwort
  • mit dem HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde. Ihr Webhook-Handler kann ebenso mit dem HTTP-Stautscode 5xx antworten, wenn Ihr Server vorübergehend Probleme hat.

Wenn der Xsolla-Server keine Antwort auf die Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung empfangen hat oder aber eine Antwort mit dem HTTP-Statuscode 5xx, werden die Webhooks gemäß dem folgenden Zeitplan erneut gesendet:

  • zwei Versuche im Abstand von 5 Minuten
  • sieben Versuche im Abstand von jeweils 15 Minuten
  • zehn Versuche im Abstand von jeweils 60 Minuten

Innerhalb von 12 Stunden nach dem ersten Versuch werden maximal 20 Versuche unternommen, Webhooks zu senden.

Wenn der Xsolla-Server keine Antwort auf den Webhook Zahlung bzw. Erstattung empfangen hat oder aber eine Antwort mit dem HTTP-Statuscode 5xx, werden die Webhooks in längeren Zeitabständen erneut gesendet. Innerhalb von 12 Stunden werden maximal 12 Versuche unternommen.

Hinweis

Wurde die Zahlungserstattung von Xsolla veranlasst und dem Webhook Erstattung mit einem HTTP-Statuscode 5xx geantwortet, wird die Zahlung trotzdem erstattet.

Wenn der Xsolla-Server keine Antwort auf den Webhook Benutzervalidierung empfangen hat oder aber eine Antwort mit dem HTTP-Statuscode 400 oder 5xx, wird der Webhook Benutzervalidierung nicht erneut gesendet. Stattdessen wird dem Nutzer eine Fehlermeldung angezeigt und die Webhooks Zahlung und Erfolgreiche Bezahlung der Bestellung werden nicht gesendet.

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 Benachrichtigungstyp Beschreibung
Benutzervalidierung user_validation Wird versendet, um zu prüfen, ob ein Benutzer im Spiel existiert.
Benutzersuche user_search Wird versendet, um Benutzerinformationen anhand der öffentlichen Benutzer-ID abzurufen.
Zahlung payment Wird versendet, wenn ein Benutzer eine Zahlung abschließt.
Erstattung refund Wird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
Teilerstattung partial_refund Wird versendet, falls eine Zahlung aus einem beliebigen Grund teilweise storniert werden muss.
Abgelehnte Transaktion (AFS) afs_reject Wird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird.
Aktualisierte AFS-Blockliste afs_black_list Wird bei Aktualisierung der AFS-Blockliste versendet.
Abgeschlossenes Abonnement create_subscription Wird versendet, wenn ein Benutzer ein Abonnement abschließt.
Aktualisiertes Abonnement update_subscription Wird versendet, wenn ein Abonnement erneuert oder geändert wird.
Storniertes Abonnement cancel_subscription Wird versendet, wenn ein Abonnement gekündigt wird.
Automatisch endendes Abonnement non_renewal_subscription Wird versendet, wenn der Status auf "Automatisch endend" gesetzt wird.
Zahlungskonto hinzufügen payment_account_add Wird versendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert.
Zahlungskonto entfernen payment_account_remove Wird versendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt.
Benutzervalidierung im Web Shop - Wird von einer Web Shop-Seite gesendet, um zu prüfen, ob ein Benutzer im Spiel vorhanden ist.
Katalogpersonalisierung aufseiten des Partners partner_side_catalog Wird gesendet, wenn ein Benutzer mit dem Shop interagiert.
Erfolgreiche Bezahlung der Bestellung order_paid Wird gesendet, wenn eine Bestellung bezahlt wurde.
Stornierung der Bestellung order_canceled Wird gesendet, wenn eine Bestellung storniert wird.
Streitfall dispute Wird gesendet, wenn ein neuer Streiftall eröffnet wird.