Gwarancje dostarczania
Co najmniej raz, brak kolejności, limit 10 sekund, drabinka ponowień i automatyczne wyłączenie — kontrakt, który musi znać każdy odbiornik.
Liczby w tej tabeli pochodzą z tego samego pliku konfiguracji, którego używa nasz mechanizm wysyłki — strona nie może się od niego rozjechać.
| Limit czasu na odpowiedź | 10 s |
|---|---|
| Drabinka ponowień | 1 min → 5 min → 30 min → 2 h → 8 h → 24 h (7 prób łącznie) |
| Automatyczne wyłączenie | 20 nieudanych dostarczeń z rzędu ORAZ brak sukcesu przez 72 h |
| Tolerancja znacznika czasu w podpisie | ±5 min |
| Stary sekret podpisuje jeszcze przez | 24 h po rotacji |
| Nagłówek podpisu | Mediflo-Signature |
| Nagłówek identyfikatora zdarzenia | Mediflo-Event-Id |
| Nagłówek typu zdarzenia | Mediflo-Event-Type |
| Nagłówek zdarzenia testowego | Mediflo-Event-Test |
Zasady, które musi respektować Twój odbiornik
Co najmniej raz. To samo zdarzenie może przyjść więcej niż raz: ponowienie po przekroczeniu czasu, które Twój serwer jednak przetworzył, ręczna ponowna wysyłka, okno rotacji sekretu. Deduplikuj po id koperty (wartość evt_… jest stała dla każdej próby tego samego zdarzenia) i pisz handler idempotentnie. Mediflo-Event-Id niesie tę samą wartość w nagłówku.
Brak gwarancji kolejności. Dostarczenia to niezależne zadania — task.updated może dotrzeć przed task.created, po którym następuje. Porządkuj po occurredAt z koperty, nigdy po kolejności przyjścia. Payload z polem revision traktuj jako wiążący tylko wtedy, gdy jego revision jest wyższy od tego, co już zapisałeś.
Odpowiedz 2xx w 10 sekund. Wszystko inne — przekroczenie czasu, 4xx, 5xx — to nieudana próba. Najpierw potwierdź, potem rób robotę: odbiornik przetwarzający synchronicznie to najczęstsza przyczyna lawiny ponowień w stronę serwera, który przecież działa.
Przekierowania to porażki. 3xx zapisujemy jako nieudaną próbę i nigdy za nim nie podążamy. Rejestruj końcowy adres https://, nie przekierowanie.
Drabinka ponowień. Po każdej kolejnej porażce czekamy odpowiednio 1 min → 5 min → 30 min → 2 h → 8 h → 24 h, czyli 7 prób w około 35 godzin. Po ostatniej dostarczenie ma status EXHAUSTED i sami przestajemy. Gdy naprawisz odbiornik, odtwórz je przez POST /webhook-deliveries/{deliveryId}/redeliver.
Automatyczne wyłączenie. Endpoint z 20 nieudanymi dostarczeniami z rzędu i bez żadnego sukcesu przez 72 h przechodzi w stan AUTO_DISABLED i przestaje cokolwiek dostawać. Oba warunki muszą zajść jednocześnie, więc samo złe okno wdrożenia go nie wyzwoli. Dostaniesz o tym zdarzenie webhook_endpoint.auto_disabled (na pozostałe, działające endpointy). Włącz ponownie w aplikacji albo przez PATCH na endpoincie.
Parsuj pobłażliwie. Pola do payloadów dodajemy bez podbijania wersji — odrzucanie nieznanych kluczy zepsuje Twój odbiornik przy następnym wydaniu. Czytaj klucze, których potrzebujesz, resztę ignoruj. apiVersion na kopercie zmienia się tylko przy zmianie łamiącej zgodność.
Ruch testowy jest oznaczony. Wysyłka testowa niesie nagłówek Mediflo-Event-Test; przy prawdziwym zdarzeniu nagłówka nie ma (nie ma wartości false), więc poprawne sprawdzenie to obecność nagłówka, nigdy porównanie z tekstem. Odrzucaj dostarczenia testowe przed produkcyjnym przetwarzaniem.
Sekret
Sekret zwracamy dokładnie raz — wywołaniem, które go tworzy. Jest przechowywany zaszyfrowany (AES-GCM) i żaden endpoint go nie odczyta. Rotacja utrzymuje odchodzący sekret w użyciu przez 24 h obok nowego, więc odbiornik możesz wdrożyć ponownie bez utraty dostarczeń. Nigdy nie loguj sekretu, nie wstawiaj go do URL-a i nie odsyłaj w treści, która zostanie zapisana.