Dostarczenia i ponowienia

Dostarczenie to jedno zdarzenie wysłane do jednego webhooka. Ta strona opisuje, jak wygląda żądanie dostarczenia, kiedy jest uznawane za udane, jak ponawiane są nieudane dostarczenia i co się dzieje, gdy endpoint stale zwraca błędy.

Żądanie

POST /beepclock/webhooks HTTP/1.1
Host: integration.example.com
Content-Type: application/json; charset=utf-8
User-Agent: BeepClock-Webhooks/1.0
X-BeepClock-Webhook-Id: c5d8a2e7-4b19-4f63-8a0d-3e7b9c1f6a52
X-BeepClock-Event: timeEntry.created
X-BeepClock-Delivery: 8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24
X-BeepClock-Attempt: 1
X-BeepClock-Signature: t=1791788292,v1=5d1f…c2a8

{"id":"8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24","event":"timeEntry.created",…}

Ciało to koperta zdarzenia w postaci zwartego JSON-a.

Nagłówki

Nagłówek	Opis
X-BeepClock-Webhook-Id	Identyfikator webhooka, do którego należy dostarczenie.
X-BeepClock-Event	Typ zdarzenia, np. timeEntry.created. Zobacz dokumentację zdarzeń.
X-BeepClock-Delivery	Identyfikator dostarczenia, czyli klucz idempotencji. Równy polu id w kopercie.
X-BeepClock-Attempt	Numer próby, liczony od 1.
X-BeepClock-Signature	Podpis HMAC. Zobacz Weryfikacja podpisów.

Własne nagłówki skonfigurowane dla webhooka, np. Authorization, są dołączane do każdego żądania, także do zdarzeń testowych. Ich nazwy nie mogą zaczynać się od X-BeepClock- ani zastępować nagłówków transportowych, takich jak Content-Type, Host czy User-Agent. Wartości mogą zawierać tylko drukowalne znaki ASCII.

Transport

Właściwość	Reguła
Metoda	POST
URL	Wyłącznie https, bezwzględny, najwyżej 2048 znaków, bez user:password@.
Adres docelowy	Musi być publicznie osiągalny. Adresy pętli zwrotnej, prywatne, link-local, CGNAT (carrier-grade NAT), dokumentacyjne, multicast i zarezerwowane, zarówno IPv4, jak i IPv6, są blokowane. Kontrola odbywa się przy zapisie adresu URL i ponownie przy każdym połączeniu, po rozwiązaniu nazwy DNS.
Timeout	10 sekund.
Przekierowania	Nie są wykonywane. Odpowiedź 3xx jest traktowana jako niepowodzenie.
Sukces	Dowolny kod statusu 2xx. Wszystko inne, w tym timeout oraz błąd połączenia lub TLS, jest niepowodzeniem.
Treść odpowiedzi	Ignorowana.

Harmonogram ponowień

Gdy próba się nie powiedzie, BeepClock ponawia dostarczenie według stałego harmonogramu:

Próba	Opóźnienie od poprzedniej próby
1	natychmiast
2	1 minuta
3	5 minut
4	30 minut
5	2 godziny
6	8 godzin
7	24 godziny

Dostarczenie ma najwyżej 7 automatycznych prób, rozłożonych na około 35 godzin. Po ostatniej nieudanej próbie dostarczenie otrzymuje status nieudanego. Po naprawieniu endpointu nadal można je wysłać ponownie.

Automatyczne wstrzymanie

BeepClock automatycznie wstrzymuje webhook, gdy:

• endpoint odpowie kodem 410 Gone. Dostarczenie nie jest ponawiane, a webhook zostaje natychmiast wstrzymany. Zwracaj 410 tylko wtedy, gdy endpoint został trwale wyłączony.
• 20 dostarczeń z rzędu zakończyło się niepowodzeniem. Dostarczenie liczy się raz, po wyczerpaniu wszystkich prób, a każde udane dostarczenie zeruje licznik.

Gdy webhook zostanie wstrzymany automatycznie, BeepClock wysyła użytkownikom konta e-mail z przyczyną i odnośnikiem do webhooka. Na liście webhooków przyczyna jest widoczna w statusie.

Gdy webhook jest wstrzymany, automatycznie lub przez Wstrzymaj wysyłanie:

• dostarczenia oczekujące na ponowienie nie są wysyłane. Otrzymują status nieudanych z błędem Webhook is disabled or deleted.;
• zdarzenia, które wystąpią w czasie wstrzymania, nie są dostarczane później. Po wybraniu Wznów wysyłanie wysyłane są tylko nowe zdarzenia.

Dziennik dostarczeń

Strona webhooka pokazuje wszystkie dostarczenia z ostatnich 30 dni, od najnowszych, z możliwością filtrowania po statusie. Wybierz dostarczenie, aby zobaczyć:

• każdą próbę z kodem statusu HTTP, czasem trwania i błędem;
• dokładny payload, który został wysłany;
• termin następnej próby, jeśli dostarczenie wciąż oczekuje.

Ponowne wysłanie dostarczenia

Wyślij ponownie w szczegółach dostarczenia wysyła je jeszcze raz z tym samym identyfikatorem dostarczenia i tą samą treścią. Numer próby jest kontynuacją wcześniejszych prób: dostarczenie udane w próbie 1 zostanie wysłane ponownie jako próba 2.

Ponowne wysłanie jest możliwe, gdy webhook jest aktywny, a dostarczenie już nie oczekuje na wysłanie. Dostarczenie, które oczekuje ponad godzinę dłużej niż zaplanowana próba, np. po przerwanym wysyłaniu, również można wysłać ponownie.

Jeśli ponownie wysłana próba się nie powiedzie, automatyczne ponowienia są kontynuowane od tego numeru próby; od próby 7 kolejnych automatycznych ponowień nie ma. Ponownie wysłane dostarczenie liczy się do automatycznego wstrzymania tak jak każde inne.

Zdarzenia testowe

Wyślij zdarzenie testowe natychmiast wysyła podpisane zdarzenie webhook.test z bieżącym sekretem i własnymi nagłówkami oraz pokazuje odpowiedź. Zdarzenie testowe:

• za każdym razem ma nowy, losowy identyfikator dostarczenia i X-BeepClock-Attempt: 1;
• jest wysyłane raz i nigdy nie jest ponawiane;
• nie trafia do dziennika dostarczeń i nie liczy się do automatycznego wstrzymania;
• można je wysłać także przy wstrzymanym webhooku, aby sprawdzić endpoint przed wznowieniem.

Idempotencja i kolejność

Gwarancja dostarczenia to co najmniej raz: to samo zdarzenie może dotrzeć do endpointu więcej niż raz, np. gdy odpowiedź 2xx zaginie w drodze powrotnej.

• Identyfikator dostarczenia (X-BeepClock-Delivery, równy polu id w kopercie) jest deterministyczny dla każdej pary webhooka i zdarzenia źródłowego. Automatyczne ponowienia i ręczne ponowne wysłania mają ten sam identyfikator i tę samą treść; zmieniają się tylko X-BeepClock-Attempt, t i podpis.
• Zapisuj identyfikatory przetworzonych dostarczeń i traktuj powtórzone dostarczenie jako nieszkodliwe.
• Kolejność nadejścia nie jest gwarantowana. Z powodu ponowienia starsze zdarzenie może dotrzeć po nowszym. Do porządkowania zdarzeń dotyczących tego samego obiektu używaj occurredAt.