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 den Verkauf von Spielschlüsseln ist eine Benutzervalidierung und die Anrechnung von Artikeln nicht erforderlich. Sie können Webhooks verknüpfen, wenn Sie Informationen über Ereignisse, wie z. B. Zahlungen oder Stornierungen der Bestellung, erhalten möchten.

Wenn Sie Webhooks verknüpfen, ist es wichtig, alle eingehenden erforderlichen Webhooks zu verarbeiten.

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:

So testen Sie Webhooks:

1. Wechseln Sie im Testbereich für Webhooks zur Registerkarte Payments und Store.
2. Wählen Sie im Drop-down-Menü die Option Spielschlüssel aus. Wenn in Ihrem Projekt keine Spielschlüsselpakete konfiguriert sind, wird eine Schaltfläche angezeigt, über die Sie die Pakete 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.