Was der Kartenbuchungs-Webhook ist und wer ihn aufruft
Der Kartenbuchungs-Webhook ist der Integrationspunkt zwischen dem bestehenden KD-System und InnerWeb. Das KD-System sendet bei jeder Kartenbuchung am Leser einen HTTP-POST-Aufruf an InnerWeb. Es müssen keine neuen Leser installiert, keine Leitungen verändert und keine Karten getauscht werden: InnerWeb ist Softwarehersteller und bindet das KD ein, das der Betrieb bereits besitzt.
Aufrufer ist immer das KD-System, nicht InnerWeb. Der Anbieter oder Administrator des KD konfiguriert die Regel, die das Ereignis nach der Buchung versendet. Auf der Seite von InnerWeb wird die Buchung der Person zugeordnet, gegen die Schulung geprüft und im Kontoverlauf gespeichert. So wird die Kartennummer aus dem KD zum Schlüssel für gültige Arbeitsschutzschulungen, Qualifikationen und Erlaubnisse.
Wie der Aufruf authentifiziert wird und wie lange der Token gilt
Der Webhook-Aufruf benötigt ein JWT-Token. Der Integrator holt es vom Anmeldeendpunkt der API und fügt es jeder Anfrage mit einer Buchung hinzu. Das Token hat eine begrenzte Gültigkeitsdauer und wird durch die Integration automatisch erneuert. Der Integrator sollte in seiner Spezifikation festhalten, wie die Sitzung erneuert wird, denn davon hängt die Kontinuität der Buchungsübermittlung ab.
Ein bewährtes Muster: ein technisches Konto, das nur für die Integration dient, Anmeldung beim Start des Dienstes, automatische Erneuerung des Tokens mit Reserve vor Ablauf und erneute Anmeldung nach einer Antwort mit abgelehnter Autorisierung. Passwörter und Token dürfen nicht in die Protokolle des Dienstes auf Seiten des KD gelangen.
Was passiert, wenn der Token während einer Änderung abläuft
Buchungen aus einer Zeit, in der der Token ungültig war, dürfen nicht verloren gehen. Bewährt hat sich eine Warteschlange auf Seiten des KD: Ein fehlgeschlagener Aufruf landet in einem Puffer, der Dienst meldet sich erneut an und sendet die Ereignisse nacheinander nach. Die Warteschlange ist nur sinnvoll, wenn die Ereignisse nahezu in Echtzeit versendet werden, wie weiter unten beschrieben.
Felder einer Kartenbuchungsmeldung
Welche Felder in einer Buchungsmeldung Pflicht sind
Die Meldung enthält Ereigniszeit, Ort der Buchung und Personendaten. Pflicht sind Vorname und Nachname sowie der Firmenname. Optional übergeben werden Kürzel, die Nummer der aktiven Karte, Telefon, E-Mail und Sprache. Je vollständiger der Satz, desto einfacher die Zuordnung zu einem bestehenden Konto und desto besser die Benachrichtigungen in der Sprache der Person.
Die Nummer der aktiven Karte ist die Kennung, über die InnerWeb die Buchung dem Konto der Person zuordnet. Eine Fremdfirma wird anhand des Firmennamens aus der Meldung zugeordnet. Taucht dieselbe Agentur im KD einmal mit vollem Namen und einmal mit Kürzel auf, entstehen Abweichungen. Der Integrator sollte Firmennamen deshalb einheitlich schreiben.
- Pflicht: Vorname und Nachname der Person sowie der Firmenname.
- Empfohlen: Nummer der aktiven Karte als Zuordnungsschlüssel zum Konto.
- Optional: Kürzel, Telefon, E-Mail, Sprache.
- Immer: Ereigniszeit und Ort der Buchung.
Was geschieht bei einer unbekannten Karte oder Person
Eine Buchung durch eine dem System unbekannte Person legt ein Konto und eine Firma aus den Daten der Meldung an. Das ist bei hoher Fluktuation in Agenturen praktisch, verlangt aber Disziplin bei den Daten: Ein Fehler in Schreibweise von Nachname oder Firma erzeugt ein Duplikat. Die Frage nach der unbekannten Karte lautet deshalb in der Praxis: Wer ist im KD für die Qualität der Quelldaten verantwortlich?
Hat dieselbe Person zwei aktive Konten, überträgt das System das Schulungsergebnis auf das Konto mit der Eingangskarte, damit das Tor keine fehlende Schulung mehr meldet. Konten werden niemals allein anhand des Nachnamens zusammengeführt, da dies zu Verwechslungen zwischen Personen mit gleichem Nachnamen führen würde.
Ereigniszeit, Richtung und Duplikate: Anforderungen an die Spezifikation
Die Integrationsspezifikation verlangt, dass das KD-System Ereignisse in Echtzeit sendet, mit der vom Leser erfassten Ereigniszeit, ohne Pakete und ohne nächtliche Übertragungen. So entsprechen die Buchungszeiten in InnerWeb den tatsächlichen Durchgängen am Tor, und Verzögerungen im Netz verfälschen die Erfassung nicht.
Jedes Ereignis aus dem KD sollte die Richtung (Eingang oder Ausgang) und eine Ereigniskennung enthalten. InnerWeb nimmt die Ereignisse über den authentifizierten Webhook entgegen. Die Regeln für die Zuordnung von Ein- und Ausgängen sowie für das Verwerfen von Duplikaten werden mit dem KD-Anbieter in der Spezifikation festgelegt. Bei Betrieben mit mehreren Agenturen kann das Aufkommen an einem Werktag 2 000 Buchungen überschreiten, daher muss die Integration Ereignisserien und Wiederholungen verkraften.
Checkliste
Videomaterial
Häufig gestellte Fragen
Müssen Leser ausgetauscht werden, um die Integration in Betrieb zu nehmen?
Nein. InnerWeb produziert und tauscht keine KD-Leser aus. Die Integration besteht aus dem Versand des Buchungsereignisses vom bestehenden KD-System an InnerWeb per HTTP-POST.
Wie funktioniert die Authentifizierung mit dem Token?
Das JWT-Token aus dem API-Anmeldeendpunkt hat eine begrenzte Gültigkeit. Die Integration erneuert es automatisch mit Reserve vor dem Ablauf.
Speichert InnerWeb die Buchungszeit des Lesers?
Die Integrationsspezifikation sieht vor, dass das KD-System Ereignisse in Echtzeit mit der Ereigniszeit des Lesers sendet.
Woher kennt InnerWeb die Richtung Eintritt und Austritt?
Richtung und Ereigniskennung sendet das KD-System. Die Regeln für die Zuordnung von Ein- und Ausgängen sowie für das Verwerfen von Duplikaten legt die Spezifikation mit dem KD-Anbieter fest.
Quellen
Sprechen wir über die Integration mit Ihrem KD
Wir übergeben dem KD-Anbieter die Webhook-Spezifikation und gehen mit ihm Felder, Token und Echtzeitversand durch. Vereinbaren Sie ein Gespräch mit dem Team von InnerWeb.
Sprechen wir