Wprowadzenie
Webhooki to jedno z tych rozwiązań, które wydają się proste – wysyłasz dane, gdy coś się dzieje. Tylko że w praktyce ta prostota bywa złudna. Pracowałem z kilkunastoma firmami, które wdrożyły webhooki w swoich systemach i… regularnie traciły dane, duplikowały zamówienia lub zawodziły w kluczowych momentach. Problem nie leży w samej technologii, ale w jej złej strategii. Poniżej przedstawiam trzy błędy, które widzę najczęściej i które realnie kosztują.
Błąd 1. Brak retry z backoffem – czyli: ufasz, że API zawsze odpowiada
Standardem przy projektowaniu webhooków jest wysłanie żądania i… jeśli nie ma odpowiedzi, to często po prostu zapominamy o zdarzeniu. W wielu systemach widzę implementację, która próbuje raz, a jeśli serwer zwróci błąd (np. 500 lub timeout), to dane przepadają. To jak wysłanie listu bez potwierdzenia odbioru.
Jak powinno być?
Każdy webhook powinien mieć mechanizm ponawiania z wykładniczym backoffem (np. 1 min, 5 min, 30 min, 2 godziny, a potem powiadomienie administratora). Bez tego tracisz zamówienia, rejestracje czy aktualizacje stanów magazynowych. Znam przypadek sklepu, który przez brak retry stracił około 15% zamówień z platformy marketplace – serwer odbierający webhook przeciążał się w szczycie, a dane znikały.
Błąd 2. Brak deduplikacji – czyli: jak dostać dwa razy to samo zamówienie
Webhooki są z natury niegwarantowane – mogą być wysłane wielokrotnie (np. z powodu timeoutu po stronie nadawcy i ponowienia). Jeśli Twój odbiorca nie obsługuje deduplikacji, możesz utworzyć dwa razy to samo zamówienie, wysłać dwa razy ten sam e-mail czy naliczyć podwójną płatność.
Rozwiązanie
Każdy webhook powinien zawierać unikalny identyfikator (idempotency key). Odbiorca powinien zapisywać ten klucz i odrzucać duplikaty. W praktyce często widzę, że implementacja opiera się na timestampach lub hashach treści – to działa słabo, bo timestamp może się powtórzyć, a hash może być identyczny dla zmodyfikowanego zdarzenia. Używaj UUID generowanego przez nadawcę.
Błąd 3. Brak monitorowania i logowania – czyli: udajesz, że wszystko działa
Większość firm wdraża webhooki i zapomina o tym, że to taki sam element infrastruktury jak API. Bez monitorowania nie wiesz, ile webhooków przepadło, ile ponowień zadziałało i jaki jest średni czas odpowiedzi. Skutek? Dowiadujesz się o problemie, gdy klient zgłosi brak zamówienia.
Co zrobić?
Zaloguj każde wejście webhooka: timestamp, payload, status odpowiedzi, czas przetwarzania. Ustaw alerty, jeśli odsetek błędów przekroczy 1%. Używaj narzędzi jak Sentry, Datadog czy nawet prostej tabelki w bazie danych. Bez tego działasz po omacku.
Podsumowanie
Webhooki to potężne narzędzie automatyzacji, ale tylko jeśli są zaimplementowane z głową. Błędy retry, deduplikacji i monitorowania to trzy najczęstsze problemy, które widzę w firmach, które przychodzą do nas z prośbą o audyt. Naprawienie ich nie jest trudne, ale wymaga świadomości i odrobiny inżynieryjnego myślenia. Jeśli Twoja automatyzacja szwankuje – zajrzyj do logów webhooków. Znajdziesz tam odpowiedzi.
