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

Wenn Sie Ereignisbenachrichtigungen erhalten möchten, implementieren Sie das Webhook-Handling:

  • Zahlung — wird gesendet, wenn eine Bestellung bezahlt wurde, und enthält die Zahlungsdaten sowie die Transaktionsdetails.
  • Bestellung erfolgreich bezahlt — wird gesendet, wenn ein Zahlung-Webhook erfolgreich verarbeitet wurde, und enthält Informationen über die gekauften Artikel und die Transaktions-ID.
  • Erstattung — wird gesendet, wenn eine Bestellung storniert wurde, und enthält die Daten der stornierten Zahlung sowie die Transaktionsdetails.
  • Bestellung storniert — wird gesendet, wenn ein Erstattung-Webhook erfolgreich verarbeitet wurde, und enthält Informationen über die gekauften Artikel und die ID der stornierten Transaktion.
  • Benutzervalidierung — wird während der verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Benutzer im Spiel registriert ist. Enthält Informationen über den Käufer des Spielschlüssels.

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

Wenn Sie eine externe ID (Transaktions-ID aus Ihrem System) verwenden und diese mit einer Transaktions-ID aufseiten von Xsolla verknüpfen oder zusätzliche Transaktionsparameter übermitteln möchten, implementieren Sie den Webhook Verknüpfung der Transaktions-ID.

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.

Achtung
Für die Datenübertragung wird das HTTPS-Protokoll verwendet; das HTTP-Protokoll wird nicht unterstützt.
  1. 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.
  2. Klicken Sie auf Webhooks aktivieren.
Hinweis
Webhooks können Sie auch über eine beliebige spezialisierte Website (z. B. webhook.site) oder Plattform (z. B. ngrok) testen.
Achtung
Sie können Webhooks nicht gleichzeitig an verschiedene URLs senden. Im Kundenportal können Sie jedoch zunächst eine URL zum Testen angeben und diese dann durch die echte URL ersetzen.
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

Sie können den Erhalt der folgenden Webhooks testen:

Webhook-NameWebhook-Typ
Benutzervalidierunguser_validation
Zahlungpayment
Bestellung storniertorder_canceled
Bestellung erfolgreich bezahltorder_paid

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

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.

Erfolgt keine Antwort auf die Webhooks Bestellung erfolgreich bezahlt und Bestellung storniert oder wurde eine Antwort mit dem Code 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 oder wurde eine Antwort mit dem Code 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 Code 400 oder 5xx empfangen, 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.

Hinweis
Die vollständige Liste und der Mechanismus der Webhook sowie detaillierte Beispiele für deren Verarbeitung sind in der Webhooks-Dokumentation beschrieben.
War dieser Artikel hilfreich?
Vielen Dank!
Gibt es etwas, das wir verbessern können? Nachricht
Das tut uns leid
Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
Vielen Dank für Ihr Feedback!
Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.
Letztmalig aktualisiert: 8. November 2024

Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.

Problem melden
Wir überprüfen unsere Inhalte ständig. Ihr Feedback hilft uns, sie zu verbessern.
Geben Sie eine E-Mail-Adresse an, damit wir Sie erreichen können
Vielen Dank für Ihr Feedback!