Webhooks einrichten

Ein Webhook ist ein Programmcode, der aus Parametern und deren entsprechenden Werten besteht. Tritt ein bestimmtes Ereignis ein, wird eine HTTP-Anfrage mitsamt den aktualisierten Parameterwerten an Ihre Anwendung gesendet. In der Regel handelt es sich dabei um eine POST-Anfrage im JSON-Format.

Beispielhafte Ereignisse: Benutzer interagiert mit einem Artikelkatalog oder bezahlt oder storniert eine Bestellung.

Liste der Webhooks

Für den voll funktionsfähigen Betrieb eines Ingame-Shops müssen Sie die Verarbeitung der wichtigsten Webhooks implementieren:

• 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 den gekauften Artikel und die Transaktions-ID. Nutzen Sie die Daten aus dem Webhook, um dem Benutzer Artikel zu gewähren.
• 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 den gekauften Artikel und die ID der stornierten Transaktion. Nutzen Sie die Daten aus dem Webhook, um dem Benutzer den gekauften Artikel zu entziehen.
• Benutzervalidierung — wird während der verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Benutzer im Spiel registriert ist.

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 Parameter bei der Validierung des Benutzers übermitteln möchten, implementieren Sie den Webhook Verknüpfung der Transaktions-ID.

Webhooks im Kundenportal einrichten

So richten Sie Webhooks ein:

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
3. Stellen Sie den Schalter Webhooks auf Ein.
4. Geben Sie die URL, unter der Sie Webhooks empfangen möchten, im folgenden Format an: https://example.com.
5. Ein geheimer Schlüssel zum Signieren von Projekt-Webhooks wird standardmäßig generiert. Wenn Sie einen neuen geheimen Schlüssel generieren möchten, klicken Sie auf das Aktualisieren-Symbol.
6. Klicken Sie auf Einstellungen speichern.

Webhooks im Kundenportal testen

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 Parameter bei der Validierung des Benutzers übermitteln möchten, implementieren Sie den Webhook Verknüpfung der Transaktions-ID.

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

• Bestellung erfolgreich bezahlt und Bestellung storniert
• Zahlung und Benutzervalidierung

So testen Sie die Webhooks Bestellung erfolgreich bezahlt und Bestellung storniert:

1. Wechseln Sie im Testblock für Webhooks zur Registerkarte Online-Shop.
2. Wählen Sie im Drop-down-Menü den Artikeltyp aus. Ist der ausgewählte Artikeltyp nicht im Kundenportal eingerichtet, wird eine der folgenden Schaltflächen angezeigt:
   • Verknüpfen, sofern das Modul für diesen Artikeltyp nicht verknüpft ist
   • Konfigurieren, sofern das Modul bereits verknüpft, aber die Einrichtung noch nicht abgeschlossen ist

3. Geben Sie im Feld Xsolla-Bestell-ID einen beliebigen Wert ein.
4. Wählen Sie die SKU der jeweiligen Artikel aus der Drop-down-Liste aus, und geben Sie den Betrag an. Sie können mehrere Artikel desselben Typs auswählen, indem Sie auf + klicken und einen weiteren Artikel in einer neuen Zeile hinzufügen.
5. Wählen Sie die Währung, in der Bestellung bezahlt werden soll.
6. Klicken Sie auf Test.

Die Webhooks Bestellung erfolgreich bezahlt und Bestellung storniert mit den angegebenen Daten werden an die festgelegte URL gesendet. Die Testergebnisse für jeden Webhook-Typ werden unter der Schaltfläche Test angezeigt.

Hinweis

Wird im Testblock eine Fehlermeldung angezeigt, wonach der Test nicht erfolgreich war, sollten Sie die Webhook-Antworteinstellungen in Ihrem Webhook-Listener überprüfen. Informationen über diese Fehler sind in den Testergebnissen ersichtlich.

So testen Sie die Webhooks Zahlung und Benutzervalidierung:

1. Wechseln Sie im Testblock für Webhooks zur Registerkarte Zahlungen.
2. Füllen Sie die Pflichtfelder aus:
   • Benutzer-ID
   • Xsolla-Rechnungs-ID  – Transaktions-ID aufseiten von Xsolla
   • Betrag
   • Währung – Währung aus der Drop-down-Liste auswählen
   • Rechnungs-ID  – Transaktions-ID aufseiten Ihres Spiels

1. Zum Testen können Sie beliebige Werte eingeben.

1. Anhand des Werts im Feld Benutzer-ID wird geprüft, ob ein Benutzer im Spiel existiert. Wenn Sie während des Tests eine positive Antwort erhalten möchten, geben Sie in das Feld Benutzer-ID einen Wert ein, der von Ihrem Server erfolgreich validiert werden kann.

3. Klicken Sie auf Test.

Die Webhooks Zahlung und Benutzervalidierung mit den angegebenen Daten werden an die festgelegte URL gesendet. Die Testergebnisse für jeden Webhook-Typ werden unter der Schaltfläche Test angezeigt.

Hinweis

Wird im Testblock eine Fehlermeldung angezeigt, wonach der Test nicht erfolgreich war, sollten Sie die Webhook-Antworteinstellungen in Ihrem Webhook-Listener überprüfen. Informationen über diese Fehler sind in den Testergebnissen ersichtlich.

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