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.

Um zur neuen Option mit dem Empfang von kombinierten Webhooks zu wechseln, wenden Sie sich an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.

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

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. Ö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 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. 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.

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 im Kundenportal testen

Sofern die Webhooks erfolgreich eingerichtet sind, wird ein entsprechender Testblock unter dem Einrichtungsblock angezeigt.

Der Testbereich im Kundenportal variiert je nach der Empfangsoption für Webhooks.

De Verarbeitung der Tests für das Szenario mit kombinierten Webhooks wird im Folgenden 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)

Gehen Sie zum Testen wie folgt vor:

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. Sind im Kundenportal noch keine Spielschlüsselpakete eingerichtet, wird eine der folgenden Schaltflächen angezeigt:
   • Verknüpfen, sofern das Spielschlüssel-Modul nicht verknüpft ist
   • Konfigurieren, sofern das Modul bereits verknüpft, aber die Einrichtung noch nicht abgeschlossen ist
3. Füllen Sie die notwendigen Felder aus:
   1. Geben Sie einen beliebigen Wert ins Feld Xsolla-Bestell-ID ein. Wählen Sie das Spielschlüsselpaket aus der Drop-Down-Liste.
   2. Spezifizieren Sie die Plattformen, auf denen das Spiel veröffentlicht wird.
   3. Benutzer-ID – zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
   4. 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 > Einstellungenaktiviert ist.
   5. Xsolla-Rechnungs-ID– Transaktions-ID aufseiten von Xsolla. 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.
   7. Menge – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
   8. Währung – wählen Sie ein Währung aus der Drop-down-Liste aus.
4. Klicken Sie auf Webhook testen.

Benutzervalidierung, die Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung mit den angegebenen Daten werden an die festgelegte URL gesendet. Die Testergebnisse für jeden Webhook-Typ werden unter der Schaltfläche Test angezeigt. Wenn die Public-User-ID in Ihrem Projekt 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.

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 Bestellung erfolgreich bezahlt und Bestellung storniert 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.

Erhält der Xsolla-Server keine Antwort auf die Webhooks Zahlung oder Erstattung, oder empfängt eine Antwort mit dem Code 5xx, werden die Webhooks in längeren Zeitabständen erneut gesendet. Innerhalb von 12 Stunden werden maximal 12 Versuche unternommen.

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 Bestellung erfolgreich bezahlt werden nicht gesendet.

Letztmalig aktualisiert: 23. Januar 2025