Dobre praktyki dla odbiorcy

Stosuj te praktyki, aby zbudować endpoint, który nie gubi zdarzeń, nie przetwarza ich dwukrotnie i nie da się oszukać sfałszowanymi żądaniami.

Odpowiadaj szybko, przetwarzaj później

BeepClock czeka na odpowiedź najwyżej 10 sekund. Zapisz zdarzenie, odpowiedz kodem 2xx (np. 202 lub 204) i właściwe przetwarzanie wykonaj w tle, np. z kolejki. Długie przetwarzanie w trakcie żądania grozi przekroczeniem limitu czasu, a każde przekroczenie powoduje ponowienie zdarzenia, które mogło już zostać obsłużone.

Weryfikuj każde żądanie

Weryfikuj podpis na surowym ciele, zanim sparsujesz payload lub mu zaufasz, porównuj podpisy w czasie stałym i odrzucaj żądania z przeterminowanym t. Akceptuj każdą wartość v1 z nagłówka, aby rotacja sekretu nie przerywała dostarczeń.

Obsługuj duplikaty

Gwarancja dostarczenia to co najmniej raz. Przechowuj identyfikatory dostarczeń, które zostały już przetworzone, np. w tabeli z unikalnym kluczem, i pomijaj dostarczenie o identyfikatorze, który już wystąpił. Ponowienia i ponowne wysłania zawsze powtarzają ten sam identyfikator i tę samą treść.

Nie polegaj na kolejności

Zdarzenia mogą docierać w innej kolejności, niż wystąpiły, zwłaszcza po ponowieniach. Gdy kolejność ma znaczenie, np. przy dwóch kolejnych zmianach danych pracownika, porównuj occurredAt i zachowuj najnowszy stan.

Odczytuj payload tolerancyjnie

Ignoruj pola, których nie znasz, a brakujące pola traktuj jak null. BeepClock może dodawać nowe pola bez zmiany apiVersion. Jeśli zdarzenie dotyczy obiektu, który został już usunięty, data zawiera tylko id.

Zwracaj właściwe kody statusu

Sytuacja	Odpowiedź
Zdarzenie zapisane	Dowolny 2xx
Niepoprawny lub brakujący podpis	401
Przejściowy problem po Twojej stronie	5xx albo przekroczenie limitu czasu żądania. BeepClock ponowi próbę.
Endpoint został trwale wyłączony	410 Gone. BeepClock od razu wstrzymuje webhook.

Nie odpowiadaj przekierowaniem: BeepClock nie wykonuje przekierowań i traktuje je jako niepowodzenie.

Chroń sekrety

• Przechowuj sekret podpisu i wartości własnych nagłówków, np. token API, w magazynie sekretów lub w zmiennych środowiskowych, a nie w kodzie źródłowym.
• Wygeneruj nowy sekret podpisu, jeśli stary mógł zostać ujawniony.
• Używaj HTTPS z ważnym certyfikatem. BeepClock wysyła żądania tylko na adresy https.

Monitoruj integrację

• Sprawdzaj dziennik dostarczeń po zmianach w endpoincie i używaj Wyślij zdarzenie testowe po każdym wdrożeniu.
• Upewnij się, że e-mail, który BeepClock wysyła po wstrzymaniu webhooka, trafia do osoby, która może zareagować.
• Po usunięciu awarii wyślij ponownie dostarczenia, które się nie powiodły.

Lista kontrolna

• Endpoint https, publicznie osiągalny, odpowiada 2xx w ciągu 10 sekund.
• X-BeepClock-Signature weryfikowany na surowym ciele z porównaniem w czasie stałym; kluczem jest cały sekret whsec_….
• Żądania z przeterminowanym t odrzucane (np. po 5 minutach).
• Akceptowanych jest kilka wartości v1 (rotacja sekretu).
• Deduplikacja dostarczeń po X-BeepClock-Delivery; przetwarzanie idempotentne.
• Brak założeń co do kolejności dostarczeń; occurredAt tam, gdzie kolejność ma znaczenie.
• Nieznane pola ignorowane; brakujące pola traktowane jak null.
• Szybkie 2xx i przetwarzanie w tle; 410 tylko przy trwałym wyłączeniu endpointu.