Konfiguracja webhooka

Dodatek

Webhooki są dodatkiem, który BeepClock aktywuje osobno dla każdego konta. Jeśli w menu nie ma pozycji Webhooki, skontaktuj się z BeepClock pod adresem [email protected], aby je aktywować. Zobacz Dostępność.

Ten przewodnik prowadzi od pustego endpointu do działającego webhooka w kilka minut. Potrzebny jest endpoint HTTPS, który przyjmuje żądania POST; na stronie weryfikacji podpisów znajduje się kompletny odbiorca w Node.js i C#, od którego można zacząć.

1. Przygotuj endpoint

Endpoint musi:

• używać https i być osiągalny z internetu. Adresy w sieciach prywatnych (10.x, 192.168.x, localhost i podobne) są odrzucane.
• odpowiadać dowolnym statusem 2xx w ciągu 10 sekund. Przekierowania nie są wykonywane.

Testowanie na własnym komputerze

Aby wypróbować webhooki przed wdrożeniem odbiorcy, udostępnij lokalny serwer przez tunel HTTPS, np. ngrok lub Cloudflare Tunnel, i użyj publicznego adresu tunelu jako adresu URL odbiorcy.

2. Utwórz webhook

1. Otwórz Webhooki w menu BeepClock i wybierz Dodaj webhook.
2. Wypełnij pola Nazwa, np. nazwą systemu odbierającego, i Adres URL odbiorcy.
3. W sekcji Zdarzenia wybierz zdarzenia do wysyłania. Są pogrupowane na odbicia, pracowników i urządzenia; dokumentacja zdarzeń opisuje, kiedy wysyłane jest każde z nich.
4. Opcjonalnie w sekcji Własne nagłówki dodaj nagłówki, których oczekuje endpoint, np. Authorization: Bearer …. Webhook może mieć najwyżej 10 własnych nagłówków. Ich wartości są przechowywane w postaci zaszyfrowanej i nie są ponownie wyświetlane.
5. Wybierz Zapisz.

3. Zapisz sekret podpisu

Po zapisaniu BeepClock wyświetla Sekret podpisu, czyli ciąg znaków zaczynający się od whsec_. Jest on wyświetlany tylko raz. Skopiuj go i zapisz w konfiguracji swojego systemu, np. jako zmienną środowiskową BEEPCLOCK_WEBHOOK_SECRET. Endpoint używa go do weryfikacji, czy żądania pochodzą z BeepClock.

W razie utraty sekretu wybierz Wygeneruj nowy sekret podpisu w menu webhooka. Poprzedni sekret działa jeszcze przez 24 godziny, więc można przeprowadzić rotację bez przerwy w działaniu.

4. Wyślij zdarzenie testowe

Otwórz webhook i wybierz Wyślij zdarzenie testowe. BeepClock od razu wysyła podpisane zdarzenie webhook.test i pokazuje status HTTP oraz czas odpowiedzi zwrócone przez endpoint.

Zdarzenie testowe jest wysyłane raz, nigdy nie jest ponawiane i nie pojawia się w dzienniku dostarczeń. Można je wysłać także przy wstrzymanym webhooku, aby sprawdzić endpoint przed wznowieniem.

5. Sprawdź rzeczywiste dostarczenia

Zarejestruj odbicie na rejestratorze albo zmień dane pracownika lub urządzenia i ponownie otwórz webhook. Dziennik dostarczeń zawiera wszystkie dostarczenia z ostatnich 30 dni z ich statusem, liczbą prób i ostatnią odpowiedzią. Wybierz dostarczenie, aby zobaczyć każdą próbę ze statusem HTTP, czasem trwania i błędem oraz dokładny payload, który został wysłany.

Jeśli dostarczenie się nie powiodło, popraw endpoint i wybierz Wyślij ponownie. BeepClock wysyła ten sam payload z tym samym identyfikatorem dostarczenia, dzięki czemu Twój system może je rozpoznać. Pełny opis działania znajduje się na stronie Dostarczenia i ponowienia.

Zarządzanie webhookami

Na liście webhooków i na stronie webhooka możesz:

Akcja	Działanie
Edytuj	Zmiana nazwy, adresu URL, zdarzeń lub własnych nagłówków. Pozostaw puste pole wartości nagłówka, aby zachować zapisaną wartość.
Wstrzymaj wysyłanie / Wznów wysyłanie	Zatrzymanie i wznowienie dostarczeń. Zdarzenia, które wystąpią w czasie wstrzymania webhooka, nie są wysyłane później.
Wygeneruj nowy sekret podpisu	Utworzenie nowego sekretu. Przez kolejne 24 godziny żądania są podpisywane oboma sekretami.
Usuń webhook	Usunięcie webhooka. Dostarczenia oczekujące na ponowienie nie zostaną wysłane.

Kolejne kroki

• Zweryfikuj podpisy, zanim zaufasz treści payloadu.
• Przed uruchomieniem produkcyjnym przeczytaj dobre praktyki dla odbiorcy.