InnerWeb
Zum Inhalt springen

Webhook aus dem ZKS: Leitfaden für den IT-Administrator

Der Webhook der Buchungen aus dem ZKS ist ein HTTP-Aufruf, mit dem das Zutrittskontrollsystem das Ereignis einer Kartenbuchung im Moment seines Eintretens an ein anderes System weitergibt. Der IT-Administrator sorgt dafür, dass das Ereignis tatsächlich ankommt und nicht nur gesendet wurde. Der Leitfaden zeigt, wie das Ereignis festgelegt wird, wie man es prüft und was zu tun ist, wenn das Netz des Betriebs den ausgehenden Verkehr blockiert.

89
maximales Paket der Outbox-Einträge pro Abruf
Quelle: Dokumentation der Funktion Webhook Outbox
300 s
Zeit, nach der ein nicht bestätigter Eintrag in die Warteschlange zurückkehrt
Quelle: Dokumentation der Funktion Webhook Outbox

Was ein Webhook der Buchungen aus dem ZKS bedeutet

Ein Webhook ist ein umgekehrtes Integrationsmodell: Statt das ZKS jede Minute nach neuen Buchungen abzufragen, sendet das ZKS selbst ein Ereignis an die angegebene Adresse, sobald eine Karte vorgehalten wird. Der Empfänger erhält die Daten mit geringer Verzögerung und belastet das ZKS nicht mit Abfragen.

InnerWeb nimmt die Kartenbuchungen aus dem ZKS über einen Webhook entgegen und verknüpft sie mit Qualifikationen, Freigaben, Anwesenheit und Zeiterfassung (RCP). InnerWeb ist ein Softwarehersteller: Leser und Karten produziert oder tauscht InnerWeb nicht aus, sondern integriert sich in das bestehende ZKS des Kunden. Auf Seiten des ZKS wird also eine Funktion zum Senden der Ereignisse benötigt, auf Seiten von InnerWeb eine Adresse, die sie annimmt.

Das Ereignis: was es enthalten sollte

Die Spezifikation des Ereignisses legt der IT-Administrator zusammen mit dem ZKS-Lieferanten fest. Der Mindestumfang besteht aus der Kennung der Person oder der Karte, dem Zeitstempel, der Kennung des Durchgangs und dem Ergebnis der Buchung, also Einlass erlaubt oder abgelehnt.

Liefert der Leser keine Richtung des Durchgangs, paart der Empfänger die Buchungen: Eintritt mit Austritt innerhalb eines Fensters von bis zu 13 Stunden, und Doppelbuchungen innerhalb von weniger als 180 Sekunden verwirft er. Deshalb muss der Zeitstempel genau und die Zeitzone eindeutig sein.

  • Kennung der Person oder der Karte, ohne Daten, die für den Zweck nicht benötigt werden.
  • Zeitstempel mit Zeitzone.
  • Kennung des Tores oder des Lesers.
  • Ergebnis: erlaubt oder abgelehnt.
  • Eindeutige Kennung des Ereignisses, damit eine erneute Übermittlung keine Doppelbuchung erzeugt.

Parameter für den Empfang und die Paarung der Ereignisse

Parameter für den Empfang und die Paarung der EreignisseBalkendiagramm: Schwelle für Doppelbuchungen 180 Sekunden, Rückkehr des Eintrags in die Warteschlange 300 Sekunden, Outbox-Paket 89 Einträge, Paarungsfenster 13 Stunden.0100200300Sekunden, Einträge oder Stunden (getrennte Größen)Schwelle Doppelbuchung (s): 180 Sekunden, Einträge oder Stunden (getrennte Größen)180SchwelleDoppelbuchung (s)Rückkehr in die Warteschlange (s): 300 Sekunden, Einträge oder Stunden (getrennte Größen)300Rückkehr in dieWarteschlange (s)Outbox-Paket (Einträge): 89 Sekunden, Einträge oder Stunden (getrennte Größen)89Outbox-Paket(Einträge)Paarungsfenster (h): 13 Sekunden, Einträge oder Stunden (getrennte Größen)13Paarungsfenster (h)
Quelle: Karte des Eintrags sowie Dokumentation der Funktion Webhook Outbox

Wie man prüft, dass das Ereignis ankommt

Der Antwortcode 200 auf der Senderseite ist kein Nachweis der Wirkung. Zu prüfen sind drei Dinge: ob das Ereignis im System des Empfängers erscheint, ob seine Daten stimmen und ob die Anzahl der Ereignisse der Anzahl der Buchungen im ZKS entspricht.

Die Plattform stellt eine REST-API (Versionen 1 und 2, JWT) sowie Webhooks für die Automatisierungsplattform bereit. Der Administrator kann die Anzahl der Ereignisse auf beiden Seiten über die API vergleichen und das Ergebnis unabhängig vom Bericht des Senders prüfen.

Test in drei Schritten

Der Test sollte vor der Inbetriebnahme und danach nach jeder Änderung des Netzes oder der Konfiguration des ZKS durchgeführt werden.

  • Halten Sie eine Testkarte vor und prüfen Sie, ob das Ereignis innerhalb weniger Sekunden im System des Empfängers erscheint.
  • Halten Sie dieselbe Karte zweimal innerhalb von weniger als 180 Sekunden vor und prüfen Sie, ob das Duplikat verworfen wurde.
  • Unterbrechen Sie die Verbindung kurz und prüfen Sie, ob Ereignisse nach deren Wiederherstellung nicht verloren gehen.

Wenn das Netz des Betriebs den ausgehenden Verkehr blockiert

In Betrieben mit restriktiver Netzrichtlinie ist der Anwendungsserver mitunter vom ausgehenden Verkehr abgeschnitten. Ausgehende Webhooks von InnerWeb lassen sich dann in einer Outbox-Tabelle einreihen, und ein externer Poller holt das Paket über einen eingehenden Kanal ab. Der Mechanismus betrifft das Senden von der Plattform, nicht das Empfangen der Ereignisse aus dem ZKS, doch dieselbe Regel ist beim Entwurf des Netzes zu klären.

In der Dokumentation der Funktion umfasst ein Abholpaket bis zu 89 Einträge, und ein blockierter Eintrag kehrt nach 300 Sekunden in die Warteschlange zurück, wenn er nicht bestätigt wurde. Für den Administrator sind das Parameter, die man bei der Bewertung der Verzögerung in einem abgeschotteten Netz kennen sollte.

Nachweis für die Prüfung und Wartung

Der Nachweis ist die Aufzeichnung der Ereignisse auf beiden Seiten mit denselben Kennungen. Einmal im Quartal lohnt sich der Vergleich einer Stichprobe, denn ein stiller Ausfall des Webhooks zeigt sich durch fehlende Ereignisse und nicht durch eine Fehlermeldung.

Die Scans des Durchgangs bilden die Zeiterfassung (RCP) mit Tages-, Monats- und Jahresansichten, Ausnahmelisten und dem Abschluss des Zeitraums. Fehlende Ereignisse landen also in den Ausnahmen, allerdings nur dann, wenn jemand diese Listen durchsieht.

Videomaterial

Häufig gestellte Fragen

Worin unterscheidet sich ein Webhook von einer API-Abfrage?

Ein Webhook sendet das Ereignis im Moment seines Eintretens, eine Abfrage erfordert wiederholte Anfragen. Der Webhook bietet eine geringere Verzögerung und belastet das ZKS nicht.

Wie prüft man, dass ein Ereignis nicht verloren ging?

Vergleichen Sie die Anzahl und die Kennungen der Ereignisse im ZKS und im System des Empfängers, zum Beispiel über die REST-API. Der Code 200 des Senders reicht allein nicht aus.

Was tun, wenn das Netz des Betriebs den ausgehenden Verkehr blockiert?

Ausgehende Webhooks von InnerWeb lassen sich in einer Outbox-Tabelle einreihen, und ein Poller holt das Paket über einen eingehenden Kanal ab. Das gilt für das Senden von der Plattform und ist mit der IT abzustimmen.

Prüfen wir, dass die Ereignisse aus dem ZKS ankommen

Sprechen wir über die Spezifikation des Webhooks für Ihr ZKS und über einen Test, der die Zustellung der Ereignisse bestätigt.

Sprechen wir