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:

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	Receiving information about creation, update, or cancellation of a subscription. Alternatively, you can request information via the API.
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 User authentication, if you use authentication via user ID. Alternatively, you can use user authentication via Xsolla Login.
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 Refer to the documentation for detailed information on setting up webhooks for the Digital Distribution Hub.

If you use products and solutions that require working with webhooks, enable and test the webhooks in your Publisher Account and set up their processing. When specific events occur, webhooks are sent sequentially. Therefore, if you do not process one of the webhooks, subsequent webhooks will not be sent. The list of required webhooks is presented below.

2 webhook sending options have been set up on Xsolla’s side when purchasing and returning items on the site — information with payment and transaction data and information about purchased items can come separately or can be combined into one webhook.

Receiving information in combined webhooks:

If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment of the order (order_paid) and Order cancellation (order_canceled) webhooks. In this case, you do not need to process the Payment (payment) and Refund (refund) webhooks.

Receiving information in separate webhooks:

If you registered in Publisher Account on or before January 22, 2025, you receive the following webhooks:

• Payment (payment) and Refund (refund) with information about payment data and transaction details.
• Successful payment of the order (order_paid) and Order cancellation (order_canceled) with information about purchased items.

You need to process all incoming webhooks. To switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to csm@xsolla.com.

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks.

If you receive combined webhooks:

Webhook name and type	Beschreibung
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Game services > Combined webhooks > Successful payment of the order (order_paid)	It contains payment data, transaction details, and information about purchased items. Use the data from the webhook to add items to the user.
Game services > Combined webhooks > Order cancellation (order_canceled)	It contains data of the canceled payment, transaction details, and information about purchased items. Use the data from the webhook to remove the purchased items.

If you receive separate webhooks:

Webhook name and type	Beschreibung
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Payments > Payment (payment)	It contains payment data and transaction details.
Game services > Separate webhooks > Successful payment of the order (order_paid)	It contains information about purchased items and the transaction details. Use the data from the webhook to add items to the user.
Payments > Refund (refund)	It contains payment data and transaction details.
Game services > Separate webhooks > Order cancellation (order_canceled)	It contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items.

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

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:

1. In the project in Publisher Account go to Project Settings > Webhooks section.
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.

3. 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.
4. Klicken Sie auf Webhooks aktiveren.

So deaktivieren Sie den Empfang von Webhooks:

1. In the project in Publisher Account go to Project Settings > Webhooks section.
2. Klicken Sie auf Webhooks deaktivieren.

For the webhooks in the Payment and store section, advanced settings are available. They will automatically appear under the General settings block after you click the Get webhooks button.

In this section, you can set up the receipt of additional information in webhooks. To do this, set the corresponding switches to the active position. The line of each permission indicates the webhooks that will be affected by changing the settings.

Schalter	Description
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.

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.

The testing section in the Publisher Account varies depending on the webhook receiving option.

If you receive combined webhooks:

Tab name for webhook testing	Webhook name and type
Payments and store	User validation > User validation (user_validation)
	Game services > Combined webhooks > Successful payment of the order (order_paid)
	Game services > Combined webhooks > Order cancellation (order_canceled)
Subscriptions	User validation > User validation (user_validation)
	Payments > Payment (payment)

If you receive separate webhooks:

Tab name for webhook testing	Webhook name and type
Store	Game services > Separate webhooks > Successful payment of the order (order_paid)
	Game services > Separate webhooks > Order cancellation (order_canceled)
Payments	User validation > User validation (user_validation)
	Payments > Payment (payment)
Subscriptions	User validation > User validation (user_validation)
	Payments > Payment (payment)

The process of testing for the scenario with combined webhooks is described below.

In the Payment and store tab, you can test the following webhooks:

• Benutzervalidierung (user_validation)
• Erfolgreiche Bezahlung der Bestellung (order_paid)
• Stornierung der Bestellung (order_canceled)

So testen Sie die Webhooks:

1. In the webhooks testing section, go to the Payment and store tab.

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. Fill in the necessary fields:

   1. Select the items’ SKU from the drop-down list and indicate the amount. You can choose multiple items of the same type by clicking + and adding them in a new line.
   2. User ID — when testing, you can use any combination of letters and digits.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings.
   4. Enter any value in the Xsolla Order ID field.
   5. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   6. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Currency — select a currency from the drop-down list.

4. Click Test webhooks.

User validation, Successful payment of the order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhooks button.

If public user ID is enabled in your project, you will also see the results of a user search check.

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)

To test:

1. In the testing section, go to the Subscriptions tab.
2. Fill in the necessary fields:
   1. User ID — when testing, you can use any combination of letters and digits.
   2. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings > Additional settings section.
   4. Currency — select a currency from the drop- down list.
   5. Plan ID — a subscription plan. Choose a plan from the drop-down list.
   6. Subscription product — choose a product from the drop-down list (optional).
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   9. Trial period. To test the purc hase of a subscription without a trial period or to test the renewal of a subscription, specify the value 0.
3. Click Test webhooks.

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.

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.

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

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.

If the Xsolla server did not receive a response to Successful payment of the order and Order cancellation webhooks or received a response with a 5xx code, the webhooks are resent according to the following schedule:

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

Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt. If the Xsolla server did not receive a response to Payment webhook or the Refund webhook, or received a response with a 5xx code, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.

If the Xsolla server did not receive a response to the User validation webhook or received a response with a code of 400 or 5xx, the User validation webhook is not resent. In this case, the user sees an error and the Payment and Successful payment of the order webhooks are not sent.

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

Webhook	Benachrichtigungstyp	Description
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.