Benutzerdaten (Objekt).
Webhooks (1.0)
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:
Hinweis
Je nach verwendeter Lösung und Art der Integration können die Webhooks und die Interaktionsabfolge vom angegebenen Beispiel abweichen.
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. |
| Login | Optional | Empfang von Ereignisinformationen:
Ausführliche Informationen zur Einrichtung von Webhooks finden Sie in der -Login-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:
- Zahlung (
payment) und Erstattung (refund) mit Informationen über die Zahlungsdaten und Transaktionsdetails. - Erfolgreiche Bezahlung der Bestellung (
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:
- Zahlung, Erfolgreiche Bezahlung der Bestellung und Benutzervalidierung, sofern Sie separate Webhooks empfangen
- Erfolgreiche Bezahlung der Bestellung und Benutzervalidierung, sofern Sie kombinierte Webhooks empfangen
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.
So aktivieren Sie den Empfang von Webhooks:
- Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
- Geben Sie im Feld Webhook-Server die URL Ihres Servers an, auf dem Sie Webhooks im Format
https://example.comempfangen 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.
- 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.
- 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:
- Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
- Klicken Sie auf Webhooks deaktivieren.
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:
- Benutzervalidierung (
user_validation) - Erfolgreiche Bezahlung der Bestellung (
order_paid) - Stornierung der Bestellung (
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:
- 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.
Füllen Sie die Pflichtfelder aus:
- 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.
- Benutzer- ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
- 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.
- Geben Sie einen beliebigen Wert in das Feld Xsolla- Bestell-ID ein.
- Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
- 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.
- Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
- Währung – Wählen Sie eine Währung aus der Drop-down-Liste 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:
- Benutzervalidierung (
user_validation) - Zahlung (
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:
- Wechseln Sie im Testbereich zur Registerkarte Subscriptions.
- Füllen Sie die Pflichtfelder aus:
- Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
- Xsolla-Rechnungs- ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
- 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.
- Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
- ID des Abo-Modells – Abo-Modell. Wählen Sie ein Abo-Modell aus der Drop-down-Liste.
- Abo-Produkt – Wählen Sie ein Produkt aus der Drop-down-Liste (optional).
- Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
- 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.
- Probezeitraum. Wenn Sie den Absc
hluss eines Abonnements ohne Probezeitraum oder die Verlängerung eines Abonnements testen möchten, geben Sie den Wert
0an.
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 anwendungsseitig den Empfang von Webhooks von den folgenden IP-Adressen:
185.30.20.0/24185.30.21.0/24185.30.22.0/24185.30.23.0/2434.102.38.17834.94.43.20735.236.73.23434.94.69.4434.102.22.197
Wenn Sie das Produkt Login integriert haben, müssen zusätzlich implementieren, dass Webhooks von den folgenden IP-Adressen verarbeitet werden:
34.94.0.8534.94.14.9534.94.25.3334.94.115.18534.94.154.2634.94.173.13234.102.48.3035.235.99.24835.236.32.13135.236.35.10035.236.117.164
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.
Um eine sichere Datenübertragung zu gewährleisten, müssen Sie verifizieren, ob der Webhook tatsächlich vom Xsolla-Server gesendet und während der Übertragung nicht manipuliert wurde. Generieren Sie dazu Ihre eigene Signatur basierend auf der Payload des Anfragerumpfs und vergleichen Sie diese mit der Signatur im authorization-Header der eingehenden Anfrage. Wenn die Signaturen übereinstimmen, ist der Webhook authentisch und kann gefahrlos verarbeitet werden.
Verifizierungsablauf:
Rufen Sie die Signatur aus dem
authorization-Header der eingehenden Webhook- Anfrage ab. Das Header-Format ist wie folgt:Signature <signature_value>.Rufen Sie den Webhook-Anfragerumpf im JSON-Format ab.
Hinweis
Verwenden Sie die JSON-Payload genau so, wie Sie sie erhalten haben. Die Payload darf nicht geparst oder neu codiert werden, da dies die Formatierung verändert, woraufhin die Signaturüberprüfung fehlschlägt.
Generieren Sie Ihre eigene Signatur für den Abgleich:
- Verknüpfen Sie die JSON-Payload mit dem geheimen Schlüssel Ihres Projekts, indem Sie den Schlüssel an das Ende des Strings anhängen.
- Wenden Sie die kryptografische Hash-Funktion SHA-1 auf den resultierenden String an. Als Ergebnis erhalten Sie einen hexadezimalen String aus Kleinbuchstaben.
Vergleichen Sie die generierte Signatur mit der Signatur im
authorization-Header. Wenn beide übereinstimmen, ist der Webhook authentisch.
Nachfolgend finden Sie Beispiele für die Implementierung der Signaturgenerierung für die folgenden Sprachen: C#, C++, Go, PHP und Node.js.
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"
}
}'Hinweis
Dieses Code-Beispiel ist kompatibel mit .NET Framework 4.0 und höher sowie mit .NET Core und anderen modernen .NET-Versionen. Die Signaturüberprüfung verwendet einen Vergleich mit konstanter Zeit mithilfe der ConstantTimeEquals-Methode zur Verhinderung von Timing-Angriffen.
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
public static string ComputeSha1(string jsonBody, string secretKey)
{
// Concatenation of the JSON from the request body and the project's secret key
string dataToSign = jsonBody + secretKey;
using (SHA1 sha1 = SHA1.Create())
{
byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
// Convert hash bytes to lowercase hexadecimal string
var hexString = new StringBuilder(hashBytes.Length * 2);
foreach (byte b in hashBytes)
{
hexString.Append(b.ToString("x2"));
}
return hexString.ToString();
}
}
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
string computedSignature = ComputeSha1(jsonBody, secretKey);
string receivedSignatureLower = receivedSignature.ToLower();
// Use constant-time comparison to prevent timing attacks
return ConstantTimeEquals(computedSignature, receivedSignatureLower);
}
private static bool ConstantTimeEquals(string a, string b)
{
if (a.Length != b.Length)
{
return false;
}
int result = 0;
for (int i = 0; i < a.Length; i++)
{
result |= a[i] ^ b[i];
}
return result == 0;
}
}Hinweis
Um die Convert.ToHexString-Methode nutzen zu können, brauchen Sie .NET 5.0 oder höher.
ConstantTimeEquals auch die CryptographicOperations.FixedTimeEquals-Methode verwenden.// For .NET 5.0 and later, you can use the more concise Convert.ToHexString method:
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
public static string ComputeSha1(string jsonBody, string secretKey)
{
string dataToSign = jsonBody + secretKey;
using var sha1 = SHA1.Create();
byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
return Convert.ToHexString(hashBytes).ToLower();
}
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
string computedSignature = ComputeSha1(jsonBody, secretKey);
string receivedSignatureLower = receivedSignature.ToLower();
// Use constant-time comparison to prevent timing attacks
return ConstantTimeEquals(computedSignature, receivedSignatureLower);
}
private static bool ConstantTimeEquals(string a, string b)
{
if (a.Length != b.Length)
{
return false;
}
int result = 0;
for (int i = 0; i < a.Length; i++)
{
result |= a[i] ^ b[i];
}
return result == 0;
}
}Hinweis
Wenn Sie über .NET 7.0 oder höher verfügen, könne Sie die CryptographicOperations.FixedTimeEquals-Methode verwenden.
// For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals:
using System.Security.Cryptography;
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
string computedSignature = ComputeSha1(jsonBody, secretKey);
byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature);
byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower());
return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes);
}#include <string>
#include <sstream>
#include <iomanip>
#include <openssl/sha.h>
class XsollaWebhookSignature {
public:
static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) {
// Concatenation of the JSON from the request body and the project's secret key
std::string dataToSign = jsonBody + secretKey;
unsigned char digest[SHA_DIGEST_LENGTH];
// Create SHA1 hash
SHA1(reinterpret_cast<const unsigned char*>(dataToSign.c_str()),
dataToSign.length(), digest);
// Convert to lowercase hexadecimal string
std::ostringstream hexStream;
hexStream << std::hex << std::setfill('0');
for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) {
hexStream << std::setw(2) << static_cast<unsigned int>(digest[i]);
}
return hexStream.str();
}
static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) {
std::string computedSignature = computeSha1(jsonBody, secretKey);
// Timing-safe comparison
if (computedSignature.length() != receivedSignature.length()) {
return false;
}
volatile unsigned char result = 0;
for (size_t i = 0; i < computedSignature.length(); ++i) {
result |= (computedSignature[i] ^ receivedSignature[i]);
}
return result == 0;
}
};package main
import (
"crypto/sha1"
"crypto/subtle"
"encoding/hex"
"strings"
)
type XsollaWebhookSignature struct{}
func (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {
// Concatenation of the JSON from the request body and the project's secret key
dataToSign := jsonBody + secretKey
// Create SHA1 hash
h := sha1.New()
h.Write([]byte(dataToSign))
signature := h.Sum(nil)
// Convert to lowercase hexadecimal string
return strings.ToLower(hex.EncodeToString(signature))
}
func (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {
computedSignature := x.ComputeSha1(jsonBody, secretKey)
receivedSignatureLower := strings.ToLower(receivedSignature)
// Use constant time comparison to prevent timing attacks
return subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1
}<?php
class XsollaWebhookSignature
{
/**
* Compute SHA1 signature from webhook JSON body and secret key
*
* @param string $jsonBody The raw JSON body from webhook
* @param string $secretKey The project's secret key
* @return string The lowercase SHA1 signature
*/
public static function computeSha1(string $jsonBody, string $secretKey): string
{
// Concatenation of the JSON from the request body and the project's secret key
$dataToSign = $jsonBody . $secretKey;
// Generate SHA1 signature
$signature = sha1($dataToSign);
return strtolower($signature);
}
/**
* Verify webhook signature using timing-safe comparison
*
* @param string $jsonBody The raw JSON body from webhook
* @param string $secretKey The project's secret key
* @param string $receivedSignature The signature from authorization header
* @return bool True if signature is valid, false otherwise
*/
public static function verifySignature(string $jsonBody, string $secretKey, string $receivedSignature): bool
{
$computedSignature = self::computeSha1($jsonBody, $secretKey);
// Use hash_equals for timing-safe comparison
return hash_equals($computedSignature, strtolower($receivedSignature));
}
}
?>const crypto = require('crypto');
class XsollaWebhookSignature {
// IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla
static computeSha1(jsonBody, secretKey) {
// Concatenation of the JSON from the request body and the project's secret key
const dataToSign = jsonBody + secretKey;
// Create SHA1 hash
const hash = crypto.createHash('sha1');
hash.update(dataToSign, 'utf8');
// Convert to lowercase hexadecimal string
return hash.digest('hex').toLowerCase();
}
static verifySignature(jsonBody, secretKey, receivedSignature) {
const computedSignature = this.computeSha1(jsonBody, secretKey);
const cleanReceivedSignature = receivedSignature.toLowerCase();
// Check if signatures have the same length before using timingSafeEqual
if (computedSignature.length !== cleanReceivedSignature.length) {
return false;
}
try {
return crypto.timingSafeEqual(
Buffer.from(computedSignature, 'hex'),
Buffer.from(cleanReceivedSignature, 'hex')
);
} catch (error) {
// Return false if there's any error (e.g., invalid hex characters)
return false;
}
}
}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.
Die Logik für das erneute Senden der Webhooks Zahlung und Erstattung ist auf der jeweiligen Webhook- Seite beschrieben.
Hinweis
Die Zahlung wird dem Nutzer auch dann erstattet, wenn alle folgenden Bedingungen erfüllt sind:
- Xsolla hat die Erstattung veranlasst.
- Als Antwort auf einen Webhook wurde ein Statuscode
4xxzurückgegeben, oder es wurde nach allen weiteren Zustellversuchen keine Antwort empfangen, oder es wurde der Statuscode5xxzurückgegeben.
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 Zahlung | ps_declined | Wird versendet, wenn eine Zahlung vom Zahlungssystem abgelehnt wird. |
| 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. |
OpenAPI-Beschreibung herunterladen
Sprachen
Server
Mock server
https://xsolla.redocly.app/_mock/de/webhooks/
https://api.xsolla.com/merchant/v2/
Anfrage
Xsolla sendet den Webhook partner_side_catalog mitsamt der Benutzer- und Projektparameter an die Webhook-URL, wenn ein Benutzer mit dem Shop interagiert.
Geben Sie eine Liste der item_id oder der SKUs der für den Benutzer erhältlichen Artikel zurück. In diesem Fall können Sie auch die Information einfügen, dass ein bestimmter Benutzer eine bestimmte Menge eines bestimmten Produkts kaufen kann. Mit dieser Funktion können Sie die Anzahl und Art der Produkte steuern, die der Benutzer in den Warenkorb legen und kaufen kann.
Es wird empfohlen, den Webhook partner_side_catalog in weniger als drei Sekunden zu verarbeiten.
Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Nutzersprache. Sprachencode, bestehend aus 2 Kleinbuchstaben.
- Mock serverhttps://xsolla.redocly.app/_mock/de/webhooks/personalized-partner-catalog
- https://api.xsolla.com/merchant/v2/personalized-partner-catalog
- CURL
- Payload
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'authorization: Signature d90d319f05df7b0f86d2485f48e7079f0f752523' \
-d '{
"notification_type": "partner_side_catalog",
"user": {
"user_id": "12345",
"country": "US"
}
}'Gibt eine Liste der für den Benutzer verfügbaren Artikel zurück und gibt an, wie oft ein bestimmter Benutzer einen bestimmten Artikel kaufen kann.
Any of:
One of:
Array von Objekten mit Bundle-Inhalten für die Anzeige im Katalog. Kann nur für den Bundle-Typ partner_side_content verwendet werden.
Datum, ab dem der Artikel erhältlich ist. Formatiert gemäß dem Standard RFC 3339.
Datum, ab dem der Artikel nicht mehr erhältlich ist. Formatiert gemäß dem Standard RFC 3339.
Im Katalog anzuzeigende Artikelbeschreibung. Überschreibt die im Artikel gespeicherte Beschreibung.
URL des im Katalog anzuzeigenden Bilds. Überschreibt die im Artikel gespeicherte Bild-URL. Nur das HTTPS-Protokoll wird unterstützt. Entspricht die URL nicht den Vorgaben, wird sie ignoriert.
Ein JSON-Objekt mit den Artikelattributen und den zugehörigen Werten. Überschreibt die im Artikel gespeicherten custom_attributes. Wenn das JSON die Vorgaben nicht erfüllt oder die maximale Länge überschreitet, wird es ignoriert.
Im Katalog anzuzeigender Artikelname. Überschreibt den im Artikel gespeicherten Namen.
Die im Kundenportal angegebene eindeutige ID des Artikels. Sie sollten entweder die sku oder die item_id übermitteln.
Anzahl der Artikel, die ein einzelner Nutzer kaufen kann. Um eine unbegrenzte Menge festzulegen, müssen Sie null übermitteln . Um den Artikel für den Kauf zu sperren, ihn aber im Katalog sichtbar zu lassen, müssen Sie "0" übermitteln.
Wenn Sie diesen Parameter verwenden, werden die Kauflimitinformationen nicht im Katalog angezeigt. Um diese Informationen im Katalog anzuzeigen (z. B. "7/10"), müssen Sie das Paar available und total anstelle von quantity übermitteln.
Antwort
application/json
[ { "date_from": "2024-08-11T23:59:59+08:00", "date_until": "2024-08-12T23:59:59+08:00", "quantity": 0, "sku": "com.xsolla.boots_1" }, { "date_from": "2024-08-11T23:59:59+08:00", "date_until": "2024-08-12T23:59:59+08:00", "quantity": null, "sku": "com.xsolla.sword_1" }, { "quantity": 1, "sku": "com.xsolla.helmet_1" }, { "content": [ … ], "description": "Custom description", "image_url": "https://example.com/image.png", "json_attributes": { … }, "name": "Custom name", "quantity": null, "sku": "com.xsolla.custom_item_1" }, { "available": 7, "sku": "com.xsolla.limited_item_1", "total": 10 } ]