W skrócie
Spis treści
Cecha
Kto inicjuje
Kiedy dostajesz dane
Obciążenie
Świeżość informacji
Wymaga
Prosty przykład złożenia obu: bramka płatności wysyła webhook „płatność zaksięgowana”, a Twój sklep w odpowiedzi odpytuje jej API, żeby pobrać pełne szczegóły transakcji i fakturę. Webhook jest sygnałem, API dostarcza detali. Jeśli chcesz wcześniej zrozumieć samo API, zacznij od tekstu o tym, czym jest API i jak działa REST API.
Rejestrujesz adres URL. W panelu usługi, która ma wysyłać powiadomienia, podajesz swój adres odbiorczy, czyli tak zwany endpoint. To do niego trafią dane.
Payload, czyli zawartość powiadomienia, to po prostu uporządkowane dane. Identyfikator zamówienia, kwota, waluta, e-mail klienta, status. Format JSON jest tu standardem, bo łatwo go odczytać i w kodzie, i ludzkim okiem. Jeśli ten zapis jeszcze Cię onieśmiela, pomocny będzie przewodnik o JSON, XML i innych formatach danych.
Wejdź w ustawienia. W panelu WordPress przejdź do WooCommerce, potem Ustawienia, zakładka Zaawansowane i sekcja Webhooki. Kliknij „Dodaj webhook”.
Jeśli odbiorca zwraca błąd kilka razy z rzędu, WooCommerce sam wyłączy taki webhook, żeby nie zalewać martwego adresu próbami. To dobra wiadomość, bo nie zapcha Ci kolejki, ale i pułapka: po naprawie endpointu trzeba go ręcznie włączyć z powrotem.
HTTPSendpoint zawsze po szyfrowanym połączeniu, nigdy zwykłym HTTP
Pamiętaj też o idempotencji, czyli odporności na duplikaty. Nadawca, który nie dostanie odpowiedzi na czas, wyśle to samo zdarzenie ponownie. Jeśli Twój skrypt naliczy wtedy zamówienie dwa razy, masz problem. Rozwiązanie jest proste: zapamiętuj identyfikator każdego zdarzenia i ignoruj ten, który już przetworzyłeś. Endpoint webhooka warto też chronić tak samo jak resztę serwera, o czym przypomina poradnik o bezpiecznym dostępie do serwera przez SSH .
Webhooki bywają kłopotliwe w debugowaniu, bo zdarzenie dzieje się raz i znika, a Ty nie zawsze widzisz, co dokładnie przyszło. Na szczęście istnieją narzędzia, które robią z tej ulotnej wiadomości coś, co da się obejrzeć na spokojnie.
Na start użyj usługi typu webhook.site albo RequestBin. Dają Ci tymczasowy adres, na który kierujesz webhook, i pokazują w przeglądarce całą zawartość: nagłówki, podpis, payload. Dzięki temu zobaczysz dokładnie, co nadawca wysyła, zanim napiszesz choćby linijkę kodu po swojej stronie.
Kiedy testujesz integrację na komputerze lokalnym, pomoże ngrok. Tworzy publiczny adres prowadzący do Twojego laptopa, więc nadawca może dostarczyć webhook tam, gdzie normalnie by nie dotarł. To wygodny sposób, żeby uruchomić cały przepływ jeszcze przed wdrożeniem na serwer.
Gdy webhook już działa na produkcji, najlepszym przyjacielem jest log. Zapisuj każde przychodzące żądanie razem z datą, nagłówkami i odpowiedzią, jaką zwróciłeś. Gdy coś się posypie, nie będziesz zgadywać. Otworzysz log i zobaczysz, czy wiadomość w ogóle dotarła, czy raczej Twój serwer oddał błąd.
Większość problemów z webhookami nie wynika z trudnej technologii, tylko z kilku powtarzalnych potknięć. Jeśli poznasz je wcześniej, oszczędzisz sobie godzin szukania po omacku.
Endpoint odpowiada za wolno. Nadawcy zwykle czekają tylko kilka sekund. Jeśli w odpowiedzi na webhook od razu wysyłasz maile, generujesz PDF i odpytujesz trzy inne API, nie zdążysz. Odbierz dane, odeślij 200, a właściwą robotę wykonaj w tle albo w kolejce.
Brak weryfikacji podpisu. Endpoint, który przyjmuje wszystko jak leci, to otwarte drzwi. Bez sprawdzenia HMAC ktoś może podszyć się pod bramkę płatności i wysłać fałszywe „zapłacono”. Podpis to nie dodatek, tylko podstawa.
Ignorowanie duplikatów. To samo zdarzenie potrafi przyjść dwa, trzy razy, bo nadawca ponawia próby. Bez zabezpieczenia naliczysz zamówienie albo wyślesz powiadomienie wielokrotnie.
Endpoint za firewallem albo na localhost. Webhook nie dotrze do adresu, którego nie widać z internetu. Strona na lokalnym serwerze, blokada na zaporze albo wymóg logowania na endpoincie skutecznie odetną dostawę.
Brak logów. Webhook bez logu to wiadomość, która przeszła i nie zostawiła śladu. Gdy klient napisze, że zapłacił, a zamówienie wisi nieopłacone, bez logu zostaje Ci tylko wzruszenie ramionami.
Co to jest webhook w prostych słowach?
Webhook to automatyczne powiadomienie, które jeden system wysyła do drugiego, gdy coś się wydarzy. Zamiast pytać serwer w kółko „czy są nowe dane?”, podajesz swój adres i czekasz, aż serwer sam Cię powiadomi.
Działa to jak SMS od banku po zapłaceniu kartą. Nie sprawdzasz konta co minutę. Dostajesz wiadomość dokładnie w chwili, gdy transakcja przechodzi.
Czym webhook różni się od API?
API odpowiada, kiedy je pytasz, a webhook odzywa się sam, kiedy ma coś do przekazania. Przy API to Ty inicjujesz rozmowę i pobierasz dane. Przy webhooku kierunek się odwraca i to serwer wysyła wiadomość do Ciebie.
W praktyce często używasz obu naraz. Webhook jest sygnałem, że coś się stało, a API służy do pobrania pełnych szczegółów tego zdarzenia.
Czy webhook jest bezpieczny?
Webhook jest bezpieczny, jeśli weryfikujesz podpis i odbierasz dane wyłącznie po HTTPS. Sam endpoint jest publiczny, więc bez sprawdzenia autentyczności ktoś mógłby wysłać tam fałszywe żądanie.
Standardem jest podpis HMAC liczony ze wspólnego sekretu. Twój serwer porównuje go z własnym wyliczeniem i odrzuca wszystko, co się nie zgadza.
Jak przetestować webhook?
Najszybciej przez tymczasowy adres w usłudze webhook.site lub RequestBin. Pokażą Ci w przeglądarce pełną zawartość przychodzącego żądania: nagłówki, podpis i dane.
Do testów na komputerze lokalnym użyj ngrok, który udostępni Twój endpoint w internecie. Na produkcji najlepszym narzędziem jest log zapisujący każde przychodzące żądanie.
Czy webhook potrzebuje publicznego serwera?
Tak, odbiorca webhooka musi mieć adres dostępny z internetu. Nadawca nie dotrze do strony na localhost ani do endpointu ukrytego za firewallem czy wymaganym logowaniem.
Dlatego webhooki działają na hostingu albo serwerze widocznym z sieci. Do testów lokalnych obejście stanowi tunel, na przykład ngrok.
Co się dzieje, gdy webhook się nie powiedzie?
Większość usług ponawia próbę wysłania webhooka, gdy nie dostanie odpowiedzi 200. Kolejne próby przychodzą zwykle w rosnących odstępach czasu, czasem przez wiele godzin.
Dlatego Twój skrypt powinien być odporny na duplikaty i zapamiętywać identyfikatory już przetworzonych zdarzeń. Po wielu nieudanych próbach niektóre systemy, jak WooCommerce, wyłączają webhook i trzeba go włączyć ręcznie.
Czy webhook w WooCommerce wymaga programisty?
Samo dodanie webhooka w WooCommerce nie wymaga kodu. Konfigurujesz go w panelu, w sekcji Ustawienia, Zaawansowane, Webhooki, podając temat zdarzenia, adres URL i sekret.
Programista przydaje się dopiero po stronie odbiorcy, jeśli endpoint trzeba napisać samodzielnie. Gdy korzystasz z gotowej integracji albo z narzędzia w stylu Make, obejdziesz się bez niego.
