Webhooks einrichten

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

Beispielereignis:

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

Liste der Webhooks

Für die volle Operation des In-Game Stores und Zahlungsmanagements ist es notwendig, die Verarbeitung des Hauptwebhooks zu implementieren:

Das folgende Schema zeigt Ablauf beim Kauf und bei der Rückgabe von Artikeln mithilfe von kombinierten Webhooks.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

Ist die Artikelkatalog personalisierung aufseiten Ihrer Anwendung implementiert, richten Sie die Verarbeitung der Katalogpersonalisierung aufseiten des Partners ein.

Webhooks im Kundenportal einrichten

So aktivieren Sie den Empfang von Webhooks:

1. Navigieren Sie im Kundenportal zum Menüpunkt Einstellungen > Webhooks.
2. Geben Sie im Feld Webhook-Server die URL Ihres Servers an, auf dem Sie die Webhooks im Format https://example.com empfangen wollen. Sie können auch eine URL aus einem Webhook-Testtool 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 aktivieren.

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. Aktivieren Sie dazu die erforderlichen Schalter. In der Zeile der jeweiligen Berechtigung wird eine Liste der Webhooks angezeigt, die von den Einstellungen betroffen sind.

1. Navigieren Sie im Kundenportal zum Menüpunkt Einstellungen > Webhooks.
2. Klicken Sie auf Webhooks deaktivieren.

Webhooks im Kundenportal testen

Sobald Sie Webhooks in Ihrem Projekt aktiviert haben, wird im Kundenportal unter den erweiterten Einstellungen ein Bereich zum Testen von Webhooks angezeigt.

Sie können die folgenden Webhooks testen:

1. Wechseln Sie im Testbereich für Webhooks zur Registerkarte Payments und Store.
2. Wählen Sie im Drop-down-Menü den Artikeltyp aus. Wenn der ausgewählte Artikeltyp in Ihrem Projekt nicht konfiguriert ist, wird eine Schaltfläche angezeigt, über die Sie den entsprechenden Artikeltyp einrichten können.
3. Füllen Sie die erforderlichen Felder aus:
   • Xsolla-Bestell-ID – Bestell-ID aufseiten von Xsolla. Für Testzwecke können Sie einen beliebigen numerischen Wert eingeben.
   • Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Für Testzwecke können Sie einen beliebigen numerischen Wert eingeben.
   • Artikel – Artikel, für die Sie Informationen im Webhook erhalten möchten. Wählen Sie die SKU der Artikel aus der Drop-down-Liste aus, und geben Sie die Menge an. Sie können mehrere Artikel desselben Typs auswählen, indem Sie auf “+” klicken und die Daten in einer neuen Zeile hinzufügen.
   • Benutzer-ID – Für Testzwecke können Sie eine beliebige Kombination aus Buchstaben und Ziffern eingeben.
   • Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Für Testzwecke können Sie eine beliebige Kombination aus Buchstaben und Ziffern eingeben. Es handelt sich hierbei nicht um einen erforderlichen Parameter für eine erfolgreiche Zahlungsabwicklung, jedoch können Sie den Parameter übermitteln, um die Transaktions-ID in Ihrem System mit der Transaktions-ID aufseiten von Xsolla zu verknüpfen.
   • Betrag – Zahlungsbetrag. Für Testzwecke können Sie einen beliebigen numerischen Wert eingeben.
   • Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
4. Klicken Sie auf Webhook testen.

Die drei Webhooks Erfolgreiche Bezahlung der Bestellung, Stornierung der Bestellung und Benutzervalidierung werden mit den entsprechenden Daten an die angegebene URL gesendet. Die Ergebnisse der einzelnen Webhook-Tests werden unterhalb der Schaltfläche Webhook testen angezeigt. Für jeden Webhook müssen Sie beide Szenarien konfigurieren: erfolgreiche und fehlgeschlagene Verarbeitung.

Webhook-Listener

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

Signatur generieren

Beim Empfang eines Webhooks ist die Sicherheit der Datenübermittlung zu gewährleisten. Dazu muss aus den Webhook-Daten eine Signatur generiert und danach überprüft werden, ob sie mit der im HTTP-Anfrage-Header gesendeten Signatur übereinstimmt.

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.

Dem Webhook antworten

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

• HTTP-Statuscode 200, 201 oder 204 ohne Nachrichtenrumpf im Falle einer positiven Antwort.
• HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde.

Ihr Webhook-Handler kann ebenso mit einem HTTP-Statuscode 5xx antworten, falls Ihr Server vorübergehend Probleme hat.

Erhält der Xsolla-Server keine Antwort auf die Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung oder er empfängt eine Antwort mit dem Code 5xx, 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.

Die Wiederholungslogik für die beiden Webhooks Zahlung und Erstattung ist auf der jeweiligen Webhook-Seite beschrieben.

Erhält der Xsolla-Server keine Antwort auf den Webhook Benutzervalidierung oder empfängt eine Antwort mit dem Code 400 oder 5xx, wird der Webhook Benutzervalidierung nicht erneut gesendet.

In diesem Fall wird dem Benutzer ein Fehler angezeigt und die Webhooks Zahlung und Erfolgreiche Bezahlung der Bestellung werden nicht gesendet.

Konfigurieren von Artikelinformationen in Webhooks

Sie können konfigurieren, welche Artikeldaten in den Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung über den Array items integriert sind.

Aktivierung der Integration zusätzlicher Parameter

Aktivieren Sie die Integration von zusätzlichen Parametern die Folgendes angeben:

• ob der Artikel kostenlos ist (is_free)
• ob der Artikel ein Bonus ist (is_bonus)
• ob der Artikel ein Teil eines Bundles ist (is_bundle_content)

Um diese Parameter zu erhalten, müssen Sie Ihre Webhooks auf die Version 2 mithilfe des API-Aufrufs Informationen zu Webhook-Einstellungen aktualisieren umschalten. In der Version 1 (Standard) sind diese Parameter nicht verfügbar.

Beispiel eines Arrays von Artikeln mit zusätzlichen Parametern:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Deaktivierung der Integration von Bundle-Inhalten

Standardmäßig enthalten Webhooks alle Elemente aus dem Bundle als Liste einzelner Artikel. Sie können den Webhook so konfigurieren, dass er nur das Bundle selbst enthält, ohne dessen Inhalt aufzulisten.

In diesem Fall werden die im Bundle enthaltenen Artikel nicht im Array der items einbezogen. Im oben angezeigten Array wird der Artikel mit dem SKU-com.xsolla.gold_1, der Teil des Bundles ist, ausgeschlossen.

Beispiel eines Arrays von Artikeln, wenn Bundle-Inhalte deaktiviert sind:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Um die Integration des Bundle-Contents zu deaktivieren, kontaktieren Sie Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com