Webhooks ermöglichen es Ihnen, Sofortbenachrichtigungen über konfigurierte Ereignisse zu erhalten, die aufseiten von Xsolla eintreten. Mithilfe von Webhooks können Sie Back-End- und Zusatzfunktionen Ihrer Anwendung automatisieren.

Beispielhafte Ereignisse, über die Sie benachrichtigt werden können:

• Zahlungen, einschließlich Käufe von virtueller Währung und virtuellen Gegenständen
• wiederkehrende Zahlungen und Aktionen im Zusammenhang mit Abonnements
• Erstattungen

Wenn ein konfiguriertes Ereignis eintritt, benachrichtigt Xsolla Ihr System per Webhooks darüber. Beispielsweise können Sie nach dem Erhalt eines Webhooks folgendes in die Wege leiten:

• dem Benutzerkonto Guthaben gutschreiben
• neue Gegenstände für einen Benutzer freischalten
• Abonnementdienst starten
• Benutzer nach Betrugserkennung sperren

Anhand des folgenden Beispiels wird erläutert, wie ein für die Zahlungsabwicklung zuständiger Webhook funktioniert:

Damit Webhooks korrekt funktionieren, müssen folgende Einstellungen vorgenommen werden:

• Webhooks können über folgende IP-Adressen empfangen werden: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
• Die Anwendungsdatenbank darf nicht zwei erfolgreiche Transaktionen mit derselben ID enthalten.

• Eine erstellte Signatur muss mit der im HTTP-Header übermittelten übereinstimmen.
• Im Falle eines Fehlers ist der Code 400 zurückzugeben (z. B. wenn ein erforderlicher Parameter fehlt oder eine Aufladung fehlgeschlagen ist). Verwenden Sie bei vorübergehender Störung Ihrer Server den Code 500.

Da Internetverbindungen nicht immer 100 % zuverlässig sind, können Webhooks verloren gehen oder sich verzögern. Um dieses Problem zu lösen, sendet Xsolla fehlgeschlagene Webhooks erneut, bis Ihr Listener sie empfängt. Webhooks werden innerhalb von 12 Stunden nach dem Versand des vorherigen erneut gesendet, bis Ihr Listener den Empfang bestätigt. Maximal sind 12 Versuche möglich.

Digitale Signaturen ermöglichen eine sichere Datenübertragung. So generieren Sie eine Signatur:

1. Verketten Sie den JSON-Body der Anfrage mit dem geheimen Schlüssel Ihres Projekts.
2. Wenden Sie den SHA-1-Algorithmus auf den resultierenden String an.

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

Fehlercodes für den HTTP-Code 400:

Code	Nachricht
INVALID_USER	Ungültiger Benutzer
INVALID_PARAMETER	Ungültiger Parameter
INVALID_SIGNATURE	Unzulässige Signatur
INCORRECT_AMOUNT	Ungültiger Betrag
INCORRECT_INVOICE	Ungültige Rechnung

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook	Produkt/Lösung	Benachrichtigungstyp	Beschreibung
Benutzervalidierung	Bezahlstation	user_validation	Wird versendet, um zu prüfen, ob ein Benutzer im Spiel existiert.
Benutzersuche	Bezahlstation	user_search	Wird versendet, um Benutzerinformationen anhand der öffentlichen Benutzer-ID abzurufen.
Zahlung	Bezahlstation, Abonnements	payment	Wird versendet, wenn ein Benutzer eine Zahlung abschließt.
Erstattung	Bezahlstation, Abonnements	refund	Wird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
Teilerstattung	Bezahlstation	partial_refund	Wird versendet, falls eine Zahlung aus einem beliebigen Grund teilweise storniert werden muss.
Abgelehnte Transaktion (AFS)	Bezahlstation	afs_reject	Wird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird.
Aktualisierte AFS-Blockliste	Bezahlstation	afs_black_list	Wird bei Aktualisierung der AFS-Blockliste versendet.
Abgeschlossenes Abonnement	Abonnements	create_subscription	Wird versendet, wenn ein Benutzer ein Abonnement abschließt.
Aktualisiertes Abonnement	Abonnements	update_subscription	Wird versendet, wenn ein Abonnement erneuert oder geändert wird.
Storniertes Abonnement	Abonnements	cancel_subscription	Wird versendet, wenn ein Abonnement gekündigt wird.
Automatisch endendes Abonnement	Abonnements	non_renewal_subscription	Wird versendet, wenn der Status auf "Automatisch endend" gesetzt wird.
Spielschlüssel abrufen	Buy Button	get_pincode	Wird versendet, wenn die Xsolla-API den Spielschlüssel abrufen möchte.
Benutzerguthaben: Manuelle Aktualisierung	Ingame-Online-Shop	user_balance_operation	Wird versendet, wenn sich ein Benutzerguthaben manuell ändert. Operationstyp: internal.
Benutzerguthaben: Zahlung	Ingame-Online-Shop	user_balance_operation	Wird versendet, wenn ein Benutzer eine Zahlung vornimmt. Operationstyp:payment.
Benutzerguthaben: Erstattung	Ingame-Online-Shop	user_balance_operation	Wird versendet, wenn ein Benutzer die Zahlung storniert. Operationstyp: cancellation.
Benutzerguthaben: Gutschein einlösen	Ingame-Online-Shop	user_balance_operation	Wird versendet, wenn ein Benutzer einen Gutschein einlöst, um virtuelle Gegenstände oder virtuelle Währung in einem Spiel zu erhalten. Operationstyp: coupon.
Benutzerguthaben: Kauf	Ingame-Online-Shop	user_balance_operation	Wird versendet, wenn ein Benutzer in einem Spiel etwas kauft. Operationstyp: inGamePurchase.
Schlüssel aktivieren	Buy Button	redeem_key	Wird versendet, wenn ein Benutzer einen Schlüssel aktiviert.
Zahlungskonto hinzufügen	Bezahlstation	payment_account_add	Wird versendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert.
Zahlungskonto entfernen	Bezahlstation	payment_account_remove	Wird versendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt.
Benutzervalidierung im Webshop	Webshop	-	Wird von einer Webshop-Seite gesendet, um zu prüfen, ob ein Benutzer im Spiel vorhanden ist.
Verarbeitung der Auszahlungstransaktion	Auszahlungen	-	Wird gesendet, um zu signalisieren, dass die Auszahlungstransaktion erstellt wurde und momentan verarbeitet wird.
Abschluss der Auszahlungstransaktion	Auszahlungen	-	Wird gesendet, um zu signalisieren, dass die Auszahlungstransaktion erfolgreich abgeschlossen wurde.
Katalogpersonalisierung aufseiten des Partners	Ingame-Online-Shop	partner_side_catalog	Wird gesendet, wenn ein Benutzer mit dem Shop interagiert.
Erfolgreiche Bezahlung der Bestellung	Ingame-Online-Shop	order_paid	Wird gesendet, wenn eine Bestellung bezahlt wurde.
Stornierung der Bestellung	Ingame-Online-Shop	order_canceled	Wird gesendet, wenn eine Bestellung storniert wird.