Wstęp
Webhooki to jeden z tych elementów infrastruktury, który pozostaje niewidoczny, dopóki nie przestanie działać. W e-commerce odpowiadają za komunikację między systemami: powiadomienia o płatnościach, aktualizacje stanów magazynowych, wysyłkę danych do CRM czy automatyzację e-maili. I właśnie tu leży problem – wiele firm wdraża je na „chybił trafił”, a konsekwencje odbijają się na codziennej działalności.
Nie chodzi tylko o to, że webhook nie zadziała. Chodzi o to, że jego nieprzemyślana implementacja powoduje utratę zamówień, podwójne obciążenia systemów i powielanie błędów. Przeanalizowałem setki wdrożeń i widzę trzy grzechy główne.
Błąd 1: Brak obsługi retry i deduplikacji
Webhooki są z natury zawodne – sieć potrafi zgubić żądanie, serwer może być przeciążony, a błąd po stronie odbiorcy spowodować odrzucenie. Bez mechanizmu ponawiania (retry) tracisz dane ot tak.
Wyobraź sobie, że klient płaci kartą, system płatności wysyła webhook z potwierdzeniem, ale Twój serwer akurat restartuje się po wdrożeniu. Webhook nie dociera, zamówienie wisi w statusie „oczekujące”, a Ty wysyłasz klientowi przypomnienie o braku płatności. Klient dzwoni: „Zapłaciłem, a wy mnie nękacie”. Efekt? Zaufanie spada.
Standardem powinno być co najmniej 3–5 ponowień z wykładniczym backoffem. Ale to nie wszystko. Jeśli webhook dotrze po kilku sekundach, a pierwsza próba zapisu się nie powiodła, możesz mieć duplikat zamówienia. Tu wkracza deduplikacja – klucz idempotency w nagłówku lub treści pozwala odrzucić powtórki. Bez tego skończysz z podwójnymi zamówieniami i kosztownymi zwrotami.
Z praktyki: jedna z firm e-commerce, z którymi współpracowałem, miała problem z duplikatami zamówień. Okazało się, że ich dostawca płatności wysyłał ten sam webhook wielokrotnie w odstępie kilku sekund. Brak idempotency spowodował podwójne obciążenie magazynu i księgowości. Wdrożenie prostego klucza ID webhooka załatwiło sprawę.
Błąd 2: Projektowanie synchronicznych przepływów zależnych od webhooka
Kolejny częsty błąd: traktowanie webhooka jako synchronicznego wywołania, od którego zależy cały proces. Webhook powinien być sygnałem, a nie blokerem.
Przykład: system zamówień odbiera webhook o płatności, a następnie próbuje wywołać zewnętrzną usługę wysyłkową, która jest akurat wolna. Cały proces czeka. Jeśli webhook się nie powiedzie (bo zewnętrzna usługa zwróciła błąd), zamówienie przepada, a Ty musisz ręcznie interweniować.
Rozwiązaniem jest asynchroniczność. Odbierz webhook, zapisz fakt zdarzenia w kolejce (np. RabbitMQ, AWS SQS) i natychmiast zwróć 200 OK. Resztę procesuj w tle. Dzięki temu nawet jeśli któryś z kroków się wysypie, możesz go ponowić bez utraty zamówienia.
Case study: w jednym z SaaS e-commerce zauważyłem, że webhooki od bramki płatniczej często kończyły się timeoutem po stronie backendu. Powód? Aplikacja próbowała synchronicznie zapisać zamówienie, wysłać e-mail i zaktualizować magazyn. Gdy e-mail delivery serwer był przeciążony, całość się zacinała. Po zmianie na kolejkę – zero straconych zamówień.
Błąd 3: Brak monitorowania i testowania webhooków
Webhooki działają w tle – nie widzisz ich na co dzień. I właśnie dlatego często zapominasz o ich monitoringu. Aż do momentu, kiedy klient zgłasza, że nie dostał potwierdzenia zamówienia.
Powinieneś mieć dashboard, który pokazuje: liczbę odebranych webhooków, liczbę błędów, czasy odpowiedzi. Ustaw alerty na spadek liczby zdarzeń – to pierwszy sygnał, że coś jest nie tak.
Nie mniej ważne jest testowanie. Webhooki to punkt styku z zewnętrznymi systemami – zmiana po ich stronie może złamać Twój odbiór. Dlatego warto mieć środowisko testowe z narzędziami takimi jak RequestBin czy Webhook.site, gdzie możesz symulować różne scenariusze: opóźnienia, błędne dane, duplikaty.
Z doświadczenia: jedna z platform marketplace zmieniła format JSON w webhooku bez wcześniejszego powiadomienia. Sklep, który polegał na jednym polu, które nagle zniknęło, przez tydzień nie aktualizował stanów magazynowych. Klienci zamawiali niedostępne produkty, a obsługa miała piekło. Gdyby mieli automatyczne testy integracyjne, wykryliby problem natychmiast.
Podsumowanie
Webhooki to potężne narzędzie, ale wymagają szacunku. Brak retry i deduplikacji, synchroniczne uzależnienie od webhooka oraz zaniedbany monitoring – to trzy błędy, które widzę najczęściej. Ich naprawa nie wymaga wielkich nakładów, a może uratować Twój e-commerce przed utratą zamówień i frustracją klientów.
Zastanów się: czy Twój system przetrwałby, gdyby dostawca webhooków zmienił format danych z dnia na dzień? Jeśli nie – czas to sprawdzić.
Jeśli potrzebujesz wsparcia w audycie swojej architektury webhooków – JurskiTech ma praktyczne doświadczenie w projektowaniu niezawodnych przepływów danych.
