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:

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
Buy Button	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	Optional	Für die Benutzerauthentifizierung, wenn Sie Benutzer über deren ID authentifizieren. Alternativ dazu können Sie Benutzer über Xsolla Login authentifizieren.
Digital Distribution Hub	Optional	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 Mehr dazu erfahren Sie in der Webhook-Einrichtungsanleitung für den Digital Distribution Hub.

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.

Damit ein In-Game Store ordnungsgemäß funktioniert, 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.
• Erfolgreiche Bezahlung der Bestellung (order_paid) – wird gesendet, wenn ein Webhook vom Typ Zahlung erfolgreich verarbeitet wurde, und enthält Informationen über gekaufte Artikel sowie die Transaktions-ID. Verwenden Sie die Daten aus dem Webhook, um dem Nutzer Artikel zu gewähren.
• Erstattung (refund) – wird gesendet, wenn eine Bestellung storniert wird und enthält die Daten der stornierten Zahlung sowie Transaktionsdetails.
• Stornierung der Bestellung (order_canceled) – wird gesendet, wenn ein Webhook vom Typ Erstattung erfolgreich verarbeitet wurde, und 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.

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. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
3. 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.
4. 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.
5. Klicken Sie auf Webhooks aktiveren.

So deaktivieren Sie den Empfang von Webhooks:

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
3. Klicken Sie auf Webhooks deaktivieren.

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

Sie können den Empfang der folgenden Webhooks testen:

Webhook-Name	Webhook-Typ
Benutzervalidierung	user_validation
Zahlung	payment
Stornierung der Bestellung	order_canceled
Erfolgreiche Bezahlung der Bestellung	order_paid

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

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

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

So testen Sie die Webhooks:

1. Wechseln Sie im Webhooks-Testbereich zur Registerkarte 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. Geben Sie einen beliebigen Wert in das Feld Xsolla-Bestell-ID ein.
4. 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.
5. Wählen Sie die Währung, in der die Bestellung bezahlt werden soll.
6. Klicken Sie auf Webhooks testen.

Die beiden Webhooks 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.

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

• Benutzervalidierung (user_validation)
• Zahlung (payment)

So testen Sie die Webhooks:

1. Wechseln Sie im Testbereich zur Registerkarte Payments.
2. Füllen Sie die Pflichtfelder aus:
   1. Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
   2. 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.
   3. Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
   4. Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
   5. Menge – Zahlungsbetrag. 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 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.
3. Klicken Sie auf Webhooks testen.

Unter der angegebenen URL werden die Webhooks mit den ausgefüllten Daten empfangen. Die Testergebnisse jedes Webhooks, sowohl für ein erfolgreiches Szenario als auch für ein Fehlerszenario, 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.

Wenn Sie eine URL im Feld Webhook-Server speichern, erscheint der Abschnitt Erweiterte Einstellungen, in dem Sie die Berechtigungen, detaillierte Informationen in Webhooks empfangen zu dürfen, erteilen können. Stellen Sie dazu die entsprechenden Schalter auf Ein. In der Zeile der jeweiligen Berechtigung wird eine Liste der Webhooks angezeigt, die von den 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.

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

• Benutzervalidierung (user_validation)
• Zahlung (payment)

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.

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", "35.236.90.90", "34.102.38.178".

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.

Erfolgt keine Antwort auf die Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung oder wurde eine Antwort mit dem Statuscode 5xx empfangen, werden die Webhooks nach folgendem 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. Erfolgt keine Antwort auf den Webhook Zahlung bzw. Erstattung oder wurde eine Antwort mit dem Statuscode 5xx empfangen, werden die Webhooks in längeren Zeitabständen erneut gesendet. Innerhalb von 12 Stunden werden maximal 12 Versuche unternommen.

Erfolgt keine Antwort auf den Webhook Benutzervalidierung oder wurde eine Antwort mit dem Statuscode 400 oder 5xx empfangen, wird der Webhook Benutzervalidierung nicht erneut gesendet. In diesem Fall wird dem Nutzer ein Fehler 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"
    }
}

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.