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:
Wenn ein bestimmtes Ereignis eintritt, benachrichtigt Xsolla Ihr System per Webhook. Infolgedessen können Sie Aktionen einleiten, wie zum Beispiel:
Beispielhafter Webhook-Ablauf bei der 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 |
|
In-Game Store | Erforderlich |
|
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 |
|
Digital Distribution Hub | Erforderlich |
Ausführliche Informationen zum Einrichten von Webhooks für den Digital Distribution Hub finden Sie in der Dokumentation. |
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.
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:
payment
) und Erstattung (refund
) mit Informationen
über die Zahlungsdaten und Transaktionsdetails.order_paid
) und Stornierung der Bestellung (order_canceled
)
mit Informationen über die gekauften Artikel.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:
Um Abo-Modelle automatisch zu verwalten, muss die Verarbeitung der wichtigsten Webhooks implementiert sein:
user_validation
) – wird in verschiedenen Phasen des Bezahlvorgangs gesendet,
um sicherzustellen, dass der Nutzer im Spiel registriert ist.payment
) – wird gesendet,
wenn eine Bestellung bezahlt wird, und enthält Zahlungsdaten sowie
Transaktionsdetails.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.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.refund
) – wird gesendet,
wenn eine Bestellung storniert wird und enthält die Daten der stornierten
Zahlung sowie Transaktionsdetails.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.So aktivieren Sie den Empfang von Webhooks:
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.
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:
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.
|
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:
|
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:
|
Kartenmarke anzeigen | Die Marke der Karte, mit der die Zahlung getätigt wurde. Zum Beispiel: Mastercard oder Visa. |
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.
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.
Im Folgenden ist der Testvorgang für das Szenario mit kombinierten Webhooks beschrieben.
Auf der Registerkarte Payments und Store können Sie die folgenden Webhooks testen:
user_validation
)order_paid
)order_canceled
)So testen Sie die Webhooks:
Wechseln Sie im Webhooks-Testbereich zur Registerkarte Payments und Store.
Wählen Sie im Drop-down-Menü einen Artikeltyp aus. Ist der ausgewählte Artikeltyp im Kundenportal nicht eingerichtet, klicken Sie auf:
Füllen Sie die Pflichtfelder aus:
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.
Auf der Registerkarte Subscriptions können Sie die folgenden Webhooks testen:
user_validation
)payment
)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:
0
an.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.
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:
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:
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"
}
}'
Ihr Server muss wie folgt antworten, um den Empfang eines Webhooks zu bestätigen:
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:
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.
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"
}
}
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. |