Co znaczy webhook odbić z KD
Webhook to odwrócony model integracji: zamiast odpytywać system KD co minutę o nowe odbicia, system KD sam wysyła zdarzenie pod wskazany adres, gdy karta zostanie przyłożona. Odbiorca otrzymuje dane z minimalnym opóźnieniem i nie obciąża KD zapytaniami.
InnerWeb przyjmuje zdarzenia odbicia karty z systemu KD przez webhook i łączy je z kwalifikacjami, zezwoleniami, obecnością i RCP. InnerWeb jest producentem oprogramowania: czytników i kart nie produkuje ani nie wymienia, lecz integruje się z istniejącym systemem KD klienta. Po stronie KD potrzebna jest więc funkcja wysyłania zdarzeń, a po stronie InnerWeb adres, który je przyjmie.
Zdarzenie: co powinno zawierać
Specyfikację zdarzenia ustala administrator IT razem z dostawcą KD. Minimalny zestaw to identyfikator osoby lub karty, znacznik czasu, identyfikator punktu przejścia oraz wynik odbicia, czyli wejście dozwolone lub odmowa.
Jeśli czytnik nie podaje kierunku przejścia, odbicia po stronie odbiorcy paruje się: wejście z wyjściem w oknie do 13 godzin, a duplikaty w czasie krótszym niż 180 sekund odrzuca. Dlatego znacznik czasu musi być dokładny, a strefa czasowa jednoznaczna.
- Identyfikator osoby lub karty, bez danych, które nie są potrzebne do celu.
- Znacznik czasu ze strefą czasową.
- Identyfikator bramy lub czytnika.
- Wynik: dozwolone lub odmowa.
- Unikalny identyfikator zdarzenia, żeby ponowna wysyłka nie tworzyła duplikatu.
Parametry odbioru i parowania zdarzeń
Jak sprawdzić, że zdarzenie dociera
Kod odpowiedzi 200 po stronie wysyłającego nie wystarcza jako dowód skutku. Trzeba sprawdzić trzy rzeczy: czy zdarzenie pojawiło się w systemie odbiorcy, czy ma poprawne dane i czy liczba zdarzeń odpowiada liczbie odbić w KD.
Platforma udostępnia API REST (wersje 1 i 2, JWT) oraz webhooki do platformy automatyzacji. Administrator może więc porównać liczbę zdarzeń po obu stronach przez API i sprawdzić wynik niezależnie od raportu wysyłającego.
Test w trzech krokach
Test warto przeprowadzić przed uruchomieniem, a potem po każdej zmianie sieci lub konfiguracji KD.
- Przyłóż kartę testową i sprawdź, czy zdarzenie pojawiło się w systemie odbiorcy w ciągu kilku sekund.
- Przyłóż tę samą kartę dwa razy w czasie krótszym niż 180 sekund i sprawdź, czy duplikat został odrzucony.
- Odłącz łączność na krótko i sprawdź, czy zdarzenia po jej powrocie nie giną.
Gdy sieć zakładu blokuje ruch wychodzący
W zakładach z restrykcyjną polityką sieciową serwer aplikacji bywa odcięty od ruchu wychodzącego. Wychodzące webhooki InnerWeb można wtedy kolejkować w tabeli outbox, a zewnętrzny poller odbiera paczkę kanałem przychodzącym. Mechanizm dotyczy wysyłania z platformy, a nie odbioru zdarzeń z KD, ale tę samą zasadę trzeba rozstrzygnąć przy projekcie sieci.
W dokumentacji funkcji paczka pobrania obejmuje do 89 wpisów, a zablokowany wpis wraca do kolejki po 300 sekundach, jeśli nie został potwierdzony. Dla administratora to parametry, które warto znać przy ocenie opóźnienia w sieci izolowanej.
Dowód do audytu i utrzymanie
Dowodem jest zapis zdarzeń po obu stronach z tymi samymi identyfikatorami. Raz na kwartał warto porównać próbkę, bo cicha awaria webhooka objawia się brakiem zdarzeń, a nie błędem.
Skany bramy tworzą ewidencję czasu pracy (RCP) z widokami dziennymi, miesięcznymi i rocznymi, kolejkami wyjątków i zamykaniem okresu. Brakujące zdarzenia trafiają więc do wyjątków, ale tylko wtedy, gdy ktoś te kolejki przegląda.
Materiał wideo
Często zadawane pytania
Czym webhook różni się od odpytywania API?
Webhook wysyła zdarzenie w chwili jego zajścia, a odpytywanie wymaga cyklicznych zapytań. Webhook daje mniejsze opóźnienie i nie obciąża systemu KD.
Jak sprawdzić, że zdarzenie nie zginęło?
Porównaj liczbę i identyfikatory zdarzeń w systemie KD i w systemie odbiorcy, na przykład przez API REST. Sam kod 200 wysyłającego nie wystarcza.
Co zrobić, gdy sieć zakładu blokuje ruch wychodzący?
Wychodzące webhooki InnerWeb można kolejkować w tabeli outbox, a poller odbiera paczkę kanałem przychodzącym. To rozwiązanie dla wysyłania z platformy i wymaga ustalenia z IT.
Sprawdźmy, że zdarzenia z KD docierają
Porozmawiajmy o specyfikacji webhooka dla Waszego systemu KD i o teście, który potwierdzi dostarczenie zdarzeń.
Porozmawiajmy