Najczęstsza architektura integracji wygląda tak: system A wysyła webhook, system B go przyjmuje i zapisuje dane. Działa, dopóki oba systemy są dostępne, sieć nie ma zadławień, a przetwarzanie mieści się w limicie czasu odpowiedzi. Trzy warunki, z których każdy prędzej czy później zostanie złamany.
Zasada pierwsza: przyjmij i odłóż
Odbiorca webhooka powinien robić dwie rzeczy: zapisać surowe żądanie i odpowiedzieć kodem 200. Całe przetwarzanie - walidacja, mapowanie, zapis do systemu docelowego - dzieje się później, z kolejki.
Dlaczego to ważne: nadawca zwykle uznaje brak odpowiedzi w kilka sekund za błąd i ponawia wysyłkę. Jeśli przetwarzanie trwa dłużej, dostaniesz to samo zdarzenie kilka razy, w dodatku przetwarzane równolegle.
Zasada druga: idempotencja
Każde zdarzenie musi mieć identyfikator, a odbiorca musi pamiętać, które identyfikatory już przetworzył. Bez tego ponowienie po stronie nadawcy oznacza podwójne zamówienie w systemie.
Zasada trzecia: ponowienia z rosnącym opóźnieniem
Gdy system docelowy nie odpowiada, nie ponawiaj natychmiast i w pętli - dołożysz mu ruchu w najgorszym momencie. Standardem jest opóźnienie rosnące wykładniczo z losowym rozrzutem: 1 s, 2 s, 4 s, 8 s, 16 s, z limitem prób.
Które błędy w ogóle ponawiać
- Ponawiaj: błędy 5xx, przekroczenia limitu czasu, błędy sieci, odpowiedź 429 (z uwzględnieniem nagłówka
Retry-After). - Nie ponawiaj: 400 i 422 - żądanie jest nieprawidłowe i kolejna próba niczego nie zmieni.
- Zależnie od kontekstu: 401 i 403 - jeśli token wygasł, odśwież go i spróbuj raz; jeśli brak uprawnień, przerwij.
Zasada czwarta: kolejka martwych wiadomości
Po wyczerpaniu prób zdarzenie nie może zniknąć. Trafia do osobnej kolejki z pełnym kontekstem: treść żądania, wszystkie odpowiedzi, znaczniki czasu. Do tego alert i możliwość ręcznego ponowienia po naprawieniu przyczyny.
Brak takiej kolejki to najczęstsza przyczyna zdania "u nas w systemie tego zamówienia po prostu nie ma".
Co logować
- Identyfikator zdarzenia i identyfikator korelacji przechodzący przez wszystkie kroki.
- Surowe żądanie przychodzące (z maskowaniem danych wrażliwych).
- Każde wywołanie zewnętrzne: adres, kod odpowiedzi, czas trwania.
- Wynik: sukces, ponowienie, przekazanie do kolejki błędów.
Monitoring, który ma sens
Trzy metryki wystarczają na początek: liczba zdarzeń przyjętych, liczba przetworzonych i głębokość kolejki. Rosnąca kolejka przy stałym napływie oznacza, że przetwarzanie nie nadąża - i zwykle jest to widoczne na godziny przed tym, zanim ktokolwiek zgłosi problem.
Ograniczenia po stronie dostawcy
Limity zapytań są regułą, nie wyjątkiem. Przeczytaj dokumentację, zanim zbudujesz przepływ pobierający dane w pętli - wiele API dopuszcza kilkadziesiąt zapytań na minutę, a przekroczenie limitu skutkuje czasową blokadą całego klucza.
Najczęstsze pytania
Przy kilkunastu zdarzeniach dziennie i tolerancji na opóźnienia można zacząć bez kolejki, ale idempotencję warto mieć od pierwszego dnia - dopisanie jej później oznacza sprzątanie duplikatów w bazie.
Webhook, jeśli dostawca go oferuje - dostajesz dane od razu i bez zbędnych zapytań. Odpytywanie zostaje jako rozwiązanie awaryjne oraz do okresowej synchronizacji wychwytującej zdarzenia, które przepadły.
