Ereignis
Datensatz über eine Änderung an Zahlung, Spielsitzung, KYC-Prüfung, Bonus, Spielerprofil oder einem anderen Objekt.
Dokumentation / Webhooks
Webhooks und Ereigniszustellung
Richten Sie eine zuverlässige Zustellung von Status und Ereignissen zwischen Systemen ein: von der Nachrichtenerstellung und Signaturprüfung bis zur Empfangsbestätigung, erneuten Zustellung und Fehlerüberwachung.
Ereignisse
Status und Änderungen
Signatur
Authentizitätsprüfung
Wiederholungen
erneute Zustellung
Monitoring
Historie und Diagnose
Ereignisablauf
Von der Erstellung bis zur Bestätigung
01
Ereignis erstellen
Kennung, Typ, Zeit, Objekt, Status und zugehörige Daten angeben.
02
Signieren und senden
Das Ereignis über HTTPS mit Signatur und begrenztem Timeout senden.
03
Empfang bestätigen
Nach der Prüfung das Ereignis speichern und schnell eine erfolgreiche HTTP-Antwort zurückgeben.
04
Bei Fehler erneut versuchen
Die Zustellung mit zunehmenden Intervallen wiederholen und nicht zugestellte Ereignisse zur Analyse aufbewahren.
Übersicht
Ein Webhook meldet eine Statusänderung
Der Absender kann die Zustellung wiederholen, daher muss der Empfänger die Quelle prüfen, den Empfang bestätigen und jedes Ereignis nur einmal anwenden.
Bestätigung
Der Empfänger gibt nach Prüfung und zuverlässiger Speicherung des Ereignisses eine erfolgreiche HTTP-Antwort zurück.
Wiederherstellung
Erneute Zustellung und Abstimmung helfen, Daten nach vorübergehender Nichtverfügbarkeit eines der Systeme wiederherzustellen.
Ereignisstruktur
Was ein Ereignis enthalten sollte
Eine einheitliche Nachrichtenstruktur vereinfacht Prüfung, Routing, Duplikatschutz und Unterstützung verschiedener Ereignistypen.
Ereigniskennung
Ein eindeutiger Wert, mit dem das System eine erneute Zustellung erkennt und die Verarbeitungshistorie findet.
Ereignistyp
Ein klarer, stabiler Name, der die eingetretene Änderung und ihre Verarbeitung definiert.
Erstellungszeit
Datum und Uhrzeit der Ereigniserstellung im vereinbarten Format und in der vereinbarten Zeitzone.
Zugehöriges Objekt
Typ und Kennung von Zahlung, Spieler, Runde, Anfrage, Bonus oder anderem Objekt.
Schemaversion
Eine Versionsnummer hilft, die Nachrichtenstruktur sicher zu ändern, ohne aktive Integrationen zu beeinträchtigen.
Operationskorrelation
Kennung der ursprünglichen Anfrage, Transaktion, Sitzung oder Kette zusammengehöriger Aktionen.
Kontext
Marke, Projekt, Markt, Umgebung, Provider und andere Daten, die für korrektes Routing erforderlich sind.
Ereignisdaten
Der minimale Satz an Feldern, der zur Verarbeitung der Änderung oder für eine nachfolgende API-Anfrage erforderlich ist.
Signatur und Prüfung
Authentizität und Integrität des Ereignisses prüfen
Vor einer Datenänderung prüft der Empfänger sichere Verbindung, Signatur, Erstellungszeit und eindeutige Ereigniskennung.
01
Rohnachricht erfassen
Die Signatur gegen den rohen Request-Body prüfen, bevor das JSON-Format verändert wird.
02
Zeitstempel prüfen
Die Anfrage ablehnen, wenn die Ereigniszeit außerhalb des zulässigen Fensters liegt.
03
Signatur prüfen
Das vereinbarte Secret und HMAC- oder Digitalsignaturverfahren verwenden.
04
Kennung prüfen
Bestätigen, dass das Ereignis noch nicht angewendet wurde, und das Prüfergebnis speichern.
Zustellung und Wiederholungen
HTTP-Antworten und erneute Zustellung
Der Absender muss zwischen erfolgreichem Empfang, temporärem Fehler und dauerhaftem Ausfall unterscheiden, während der Empfänger schnell und eindeutig antworten muss.
Erfolgreiche HTTP-Antwort
Bestätigt, dass das Ereignis geprüft und für die weitere Verarbeitung zuverlässig gespeichert wurde.
Begrenzter Timeout
Vor der Antwort an den Absender keine langwierige Verarbeitung ausführen — zuerst das Ereignis speichern.
Erneute Zustellung
Zustellung nach einem temporären Netzwerkfehler, Nichtverfügbarkeit oder fehlender Antwort erneut versuchen.
Zunehmendes Wiederholungsintervall
Die Pause zwischen Versuchen schrittweise erhöhen, um keine zusätzliche Last zu erzeugen.
Warteschlange nicht zugestellter Ereignisse
Nach Ausschöpfung aller Versuche das Ereignis für Diagnose und manuelle Bearbeitung aufbewahren.
Manuelle erneute Zustellung
Ein Operator kann ein ausgewähltes Ereignis erneut senden, ohne eine neue Operation zu erstellen.
Zustellmonitoring
Anzahl der Versuche, Antworten, letzten Fehler und nächsten Zustellzeitpunkt verfolgen.
Warnungen
Das Team benachrichtigen, wenn Fehler zunehmen, Wiederholungen ausgeschöpft sind oder sich Ereignisse in der Warteschlange sammeln.
Ereignisverarbeitung
Duplikatschutz und Statusreihenfolge
Der Empfänger darf sich nicht auf einmalige Zustellung oder strikte Ereignisreihenfolge verlassen.
Nur einmal anwenden
Die Ereigniskennung vor einer Datenänderung speichern.
Ein wiederholtes Ereignis bestätigen, ohne erneute Belastung, Gutschrift oder Statusänderung.
Das Ereignis mit dem Objekt und seinem aktuellen Status verknüpfen.
Ereignis und Geschäftsänderung als eine konsistente Operation speichern.
Reihenfolge und Aktualität
Zeitstempel, Sequenznummer oder Ereignisversion vergleichen.
Ein Objekt nicht in einen veralteten Zustand zurücksetzen, wenn ein älteres Ereignis verspätet eintrifft.
Nur gültige Übergänge zwischen Status zulassen.
Bei Zweifeln den aktuellen Objektstatus über die API abfragen.
Tests
Was vor dem Start getestet werden muss
Erfolgreiche Zustellung, ungültige Signaturen, Duplikate, langsame Antworten, Ereignisse außerhalb der Reihenfolge und Wiederherstellung nach einem Fehler testen.
Ungültige Signatur
Veränderte Nachricht, unbekannter Schlüssel, abgelaufener Zeitstempel und nicht unterstützter Algorithmus.
Erneute Zustellung
Dasselbe Ereignis trifft vor und nach Abschluss der Verarbeitung mehrfach ein.
Langsame Antwort
Der Empfänger antwortet zu langsam, die Verbindung bricht ab oder die Bestätigung erreicht den Absender nicht.
Verarbeitung außerhalb der Reihenfolge
Ein finaler Status trifft vor einem Zwischenstatus ein, und ein älteres Ereignis wird nach einem neueren zugestellt.
Endpoint nicht verfügbar
HTTP-5xx-Fehler, DNS, TLS, Rate Limits und vollständige Ausschöpfung aller Wiederholungsversuche testen.
Zustellhistorie
Alle Versuche, Antworten, Fehler und Ergebnisse manueller erneuter Zustellungen sollten über die Ereigniskennung durchsuchbar sein.
Checkliste vor dem Start
Produktivzustellung wird aktiviert, nachdem Sicherheit, Duplikatschutz, erneute Zustellung und Fehlermonitoring geprüft wurden.
Test- und Produktivumgebung verwenden unterschiedliche Endpoints und Signatur-Secrets.
Die Signatur wird gegen die Rohnachricht zusammen mit deren Erstellungszeit geprüft.
Die Ereigniskennung wird gespeichert und schützt Operationen vor mehrfacher Ausführung.
Der Empfänger gibt nach dem Speichern des Ereignisses schnell eine erfolgreiche HTTP-Antwort zurück.
Wiederholungen, zunehmende Intervalle und manuelle erneute Zustellung sind eingerichtet.
Zustellhistorie und kennungsbasierte Suche stehen dem Supportteam zur Verfügung.
Zuverlässige Ereigniszustellung einrichten?
Stellen Sie die Ereignisliste, Empfangs-Endpunkte und Regeln für Statusübergänge bereit. APIACE hilft, Nachrichtenstruktur, Signaturprüfung, erneute Zustellung und Fehlermonitoring festzulegen.