Wprowadzenie
Webhooki to jeden z tych elementów architektury, które działają w tle i rzadko zwracają na siebie uwagę – dopóki coś nie pójdzie nie tak. W e-commerce odpowiadają za przekazywanie informacji między systemami: od potwierdzeń płatności, przez aktualizacje stanów magazynowych, po powiadomienia o wysyłce. Problem w tym, że wiele firm traktuje je jako „ustaw i zapomnij”, co prowadzi do cichych katastrof. Dane się gubią, zamówienia przepadają, a klienci dostają komunikaty, które nie mają pokrycia w rzeczywistości. Poniżej trzy realne błędy, które widzę w projektach e-commerce, i sposoby, jak je naprawić, zanim zabiorą Ci sprzedaż.
1. Brak mechanizmu ponawiania i deduplikacji
Wyobraź sobie taką sytuację: klient składa zamówienie, płaci kartą, a system płatności wysyła webhook z potwierdzeniem do Twojego backendu. W tym momencie następuje krótki zanik sieci, webhook nie dociera, a płatność zostaje uznana za „oczekującą”. Klient kontaktuje się z obsługą, a Ty tracisz czas na ręczne weryfikacje. To scenariusz z życia wzięty.
Błąd: Brak retry logic po stronie odbiorcy lub nadawcy. Wiele systemów wysyła webhooka tylko raz, a jeśli odpowiedź nie jest 200 OK, porzuca go. Z drugiej strony, jeśli odbiorca nie sprawdza idempotencji, może przetworzyć ten sam webhook wielokrotnie – co skutkuje podwójnym obciążeniem karty lub duplikacją zamówienia.
Naprawa: Zawsze implementuj mechanizm ponawiania – zarówno po stronie źródła (np. 3-5 prób z rosnącym opóźnieniem), jak i odbiorcy (przechowuj hash payloadu i odrzucaj duplikaty). Większość bramek płatności (Stripe, PayPal) wysyła nagłówek Idempotency-Key – korzystaj z niego. Jeśli budujesz własny system webhooków, dodaj X-Request-Id i sprawdzaj go po stronie klienta. To proste, ale oszczędza godziny ręcznej pracy.
2. Brak logowania i monitorowania
Słyszałem historię sklepu, który przez trzy dni nie otrzymywał powiadomień o wysyłkach. Webhooki z systemu logistycznego nie docierały z powodu zmiany adresu URL. Nikt tego nie zauważył, bo nie było żadnego alertu. Klienci zamawiali, a zamówienia wisiały w statusie „nowe”, bo magazyn nie dostawał informacji. Efekt? Opóźnienia, reklamacje, utrata zaufania.
Błąd: Webhooki działają „na ślepo”. Nie ma logów, nie ma monitoringu. Gdy coś przestaje działać, dowiadujesz się od klienta – a to za późno. Wiele firm dopiero po awarii sprawdza, czy webhooki w ogóle były wysyłane.
Naprawa: Dodaj logowanie wszystkich zdarzeń – zarówno wychodzących z systemu źródłowego, jak i przychodzących do odbiorcy. Użyj narzędzi jak Sentry, Datadog czy nawet prostego sysloga z alertem na e-mail. Zdefiniuj progi: jeśli żaden webhook nie przyszedł przez 5 minut, wyślij powiadomienie do zespołu. W praktyce oznacza to, że awarie wykrywasz, zanim wpłyną na klienta.
3. Brak walidacji i bezpieczeństwa
Webhooki to otwarte drzwi do Twojego systemu – jeśli nie są odpowiednio zabezpieczone. Zdarzają się ataki, w których atakujący wysyła fałszywe webhooki podszywające się pod zaufane źródło, co może skutkować zmianą stanu magazynu, wysyłką towaru bez płatności lub kradzieżą danych klientów. W 2023 roku głośny był przypadek sklepu, który stracił kilkaset tysięcy złotych przez brak weryfikacji podpisu webhooka.
Błąd: Brak weryfikacji autentyczności webhooka. Sprawdzanie tylko adresu IP źródła to za mało – IP można sfałszować. Wiele firm pomija implementację HMAC lub innych mechanizmów kryptograficznych, polegając na zaufaniu sieci.
Naprawa: Każdy webhook powinien być podpisany kluczem, który jest tajemnicą dzieloną między nadawcą a odbiorcą. Stripe, GitHub, Slack – wszystkie oferują nagłówki z sygnaturą. Po stronie odbiorcy oblicz hash payloadu z użyciem klucza i porównaj z nagłówkiem. Dodatkowo, waliduj strukturę danych: typ, zakresy, formaty. Nie ufaj żadnemu payloadowi bez weryfikacji. To podstawa bezpieczeństwa, ale w praktyce pomijana w pierwszej wersji.
Podsumowanie
Webhooki to szkielet integracji w e-commerce. Źle skonfigurowane mogą generować koszty, frustrację i utratę danych. Warto poświęcić czas na ich solidne zaprojektowanie: mechanizmy ponawiania, deduplikacji, logowanie, monitoring i bezpieczeństwo. To nie jest rocket science – to dobre praktyki, które odróżniają sklep działający bez zakłóceń od takiego, który regularnie traci zamówienia. Zanim następnym razem zintegrujesz kolejny system, zajrzyj do konfiguracji webhooków. Twoi klienci Ci podziękują.
