Webhooki

Dodatek

Webhooki są dodatkiem

Webhooki nie wchodzą w skład standardowych planów BeepClock i są niedostępne, dopóki BeepClock nie aktywuje ich dla Twojego konta. Aby je aktywować, skontaktuj się z BeepClock pod adresem [email protected]. Do tego czasu pozycja Webhooki nie pojawia się w menu. Zobacz Dostępność.

Webhooki wysyłają zdarzenia BeepClock do Twojego systemu zaraz po ich wystąpieniu: odbicia zarejestrowane na rejestratorze TimeLok lub dodane w aplikacji oraz zmiany pracowników i urządzeń. System płacowy, kadrowy lub integracyjny otrzymuje każde zdarzenie jako podpisane żądanie HTTPS POST, więc nie trzeba odpytywać BeepClock ani ręcznie eksportować raportów.

Jak to działa

1. Dodajesz webhook w BeepClock: adres URL endpointu i zdarzenia, które chcesz otrzymywać.
2. Gdy wystąpi jedno z tych zdarzeń, BeepClock wysyła na endpoint payload JSON i podpisuje go sekretem podpisu webhooka.
3. Endpoint weryfikuje podpis, zapisuje zdarzenie i w ciągu 10 sekund odpowiada statusem 2xx.
4. Jeśli dostarczenie się nie powiedzie, BeepClock ponawia je przez około półtorej doby. Każde dostarczenie jest widoczne w dzienniku dostarczeń webhooka przez 30 dni.

Przykład: pracownik odbija wejście na rejestratorze

{
  "id": "8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24",
  "event": "timeEntry.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "e7b1c4d2-9a35-4f68-8e0c-2d6a9f1b5c73",
    "employee": {
      "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
      "numericId": 17,
      "firstName": "Anna",
      "lastName": "Nowak"
    },
    "eventType": "in",
    "direction": "in",
    "source": "device",
    "time": "2026-10-12T08:58:10+02:00",
    "timeZone": "Europe/Warsaw",
    "device": {
      "id": "9c3a7e15-2f6b-4d84-a0e9-6b1d5c8f3a27",
      "name": "Main entrance"
    },
    "location": {
      "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
      "name": "Hall B",
      "path": [ … ]
    }
  }
}

Dostępne zdarzenia

Zasób	Zdarzenia
Odbicia	timeEntry.created, timeEntry.typeChanged, timeEntry.deleted
Pracownicy	employee.created, employee.updated, employee.archived, employee.unarchived, employee.deleted
Urządzenia	device.created, device.updated, device.deleted

Zdarzenia urządzeń oraz odbicia zarejestrowane na urządzeniu zawierają lokalizację z pełną hierarchią, np. Zakład Kraków → Hala B. Zobacz pełne payloady.

Dostępność

Webhooki są dodatkiem. Nie wchodzą w skład standardowych planów BeepClock: BeepClock włącza je osobno dla każdego konta. Aby korzystać z webhooków, skontaktuj się z BeepClock pod adresem [email protected] i poproś o aktywowanie webhooków dla swojego konta.

Po włączeniu w menu app.beepclock.com pojawia się pozycja Webhooki, a webhookami może zarządzać każdy użytkownik konta.

Co dalej

• Konfiguracja webhooka: utworzenie webhooka, zapisanie sekretu podpisu i wysłanie zdarzenia testowego.
• Dokumentacja zdarzeń: koperta zdarzenia, wszystkie typy zdarzeń i pola każdego obiektu wraz z przykładowymi payloadami.
• Weryfikacja podpisów: algorytm podpisu, gotowy kod w Node.js i C# oraz rotacja sekretu.
• Dostarczenia i ponowienia: nagłówki żądania, harmonogram ponowień, automatyczne wstrzymanie, dziennik dostarczeń i ponowne wysyłanie.
• Dobre praktyki dla odbiorcy: lista kontrolna niezawodnego i bezpiecznego endpointu.

Najczęściej zadawane pytania

Jak włączyć webhooki dla mojego konta?

Webhooki są dodatkiem, który BeepClock włącza osobno dla każdego konta. Skontaktuj się z BeepClock pod adresem [email protected] i poproś o aktywowanie webhooków. Po włączeniu w menu aplikacji pojawia się pozycja Webhooki.

Do czego można używać webhooków BeepClock?

Do przekazywania odbić do systemu płacowego lub kadrowego na bieżąco, do synchronizowania listy pracowników lub urządzeń z inną aplikacją albo do uruchamiania własnych automatyzacji, np. powiadomienia, gdy pracownik odbije wejście w określonej lokalizacji.

Czy do korzystania z webhooków potrzebny jest programista?

Tak, albo platforma integracyjna, która potrafi odbierać żądania HTTPS. Endpoint musi przyjmować żądania POST, weryfikować podpis i odpowiadać w ciągu 10 sekund. Sama konfiguracja w BeepClock zajmuje kilka minut.

Czy zdarzenia są wysyłane ponownie, jeśli mój system był niedostępny?

Tak. Nieudane dostarczenie jest ponawiane automatycznie, łącznie do 7 prób w ciągu około 35 godzin. Każde dostarczenie można też wysłać ponownie z dziennika dostarczeń przez 30 dni. Jeśli endpoint stale zwraca błędy, BeepClock wstrzymuje webhook i wysyła e-mail do użytkowników konta.

Czy webhooki są wysyłane dla zdarzeń, które wystąpiły przed utworzeniem webhooka?

Nie. Webhook otrzymuje tylko zdarzenia, które wystąpią, gdy jest aktywny. Zdarzenia, które wystąpią w czasie wstrzymania webhooka, również nie są dostarczane później.

Czy mogę ograniczyć webhook do jednej lokalizacji?

Jeszcze nie. Webhook otrzymuje wybrane zdarzenia z całego konta. Zdarzenia urządzeń oraz odbicia zarejestrowane na urządzeniu zawierają lokalizację z jej hierarchią, więc Twój system może je filtrować.