Webhook w 5 minut
Webhook to wiadomość HTTP, którą serwer wysyła automatycznie na wskazany adres URL, gdy zajdzie konkretne zdarzenie. Najczęściej jest to żądanie POST z danymi w formacie JSON. Po stronie odbiorcy działa zwykły skrypt, który odbiera tę wiadomość i coś z nią robi: zapisuje zamówienie, wysyła e-mail, aktualizuje magazyn.
Najprościej zapamiętać to przez kontrast z tradycyjnym zapytaniem. W klasycznym API to Ty pytasz serwer „masz dla mnie coś nowego?” raz na minutę albo raz na godzinę. Przy webhooku odwracasz kierunek: podajesz swój adres i mówisz „daj mi znać, kiedy coś się zmieni”. Cała reszta dzieje się sama.
Webhooki spotkasz wszędzie tam, gdzie dwa systemy muszą reagować na siebie w czasie zbliżonym do rzeczywistego. Bramki płatności potwierdzają w ten sposób transakcje. Sklepy informują hurtownie o nowych zamówieniach. Narzędzia takie jak Zapier czy Make budują na webhookach całe automatyzacje. Jeśli korzystasz z WooCommerce, masz je wbudowane w panel, bez ani jednej linijki kodu.
Czym właściwie jest webhook
Webhook bywa nazywany „odwróconym API”, bo to nie klient inicjuje rozmowę, tylko serwer sam wychodzi z informacją. Technicznie nie ma w nim nic egzotycznego. To zwykłe żądanie HTTP, takie samo jak to, które przeglądarka wysyła, otwierając stronę. Różnica tkwi w tym, kto je wywołuje i kiedy.
Wyobraź sobie aplikację dostaw jedzenia. Bez webhooka aplikacja musiałaby co kilka sekund odpytywać serwer restauracji: „zamówienie gotowe? a teraz? a teraz?”. To marnuje zasoby po obu stronach i i tak gubi parę sekund. Z webhookiem restauracja po prostu wysyła jedno powiadomienie w momencie, gdy kurier odbiera paczkę. Mniej zapytań, świeższa informacja, mniejszy rachunek za serwer.
Z punktu widzenia odbiorcy webhook to po prostu adres URL, który wystawiasz w internecie i który czeka na dane. Ten adres musi być publiczny i dostępny dla nadawcy, dlatego webhooki działają tylko tam, gdzie masz serwer albo hosting widoczny z sieci. Lokalny WordPress na własnym laptopie nadawca po prostu nie znajdzie.
Webhook a API: na czym polega różnica
Webhook i API nie są przeciwnikami, tylko dwoma sposobami wymiany danych, które dobrze się uzupełniają. API odpowiada, kiedy je pytasz. Webhook odzywa się sam, kiedy ma coś do powiedzenia. W większości realnych integracji używasz obu naraz.
| Cecha | Klasyczne API (odpytywanie) | Webhook (powiadomienie) |
|---|---|---|
| Kto inicjuje | Ty wysyłasz zapytanie do serwera | Serwer sam wysyła dane do Ciebie |
| Kiedy dostajesz dane | Dopiero gdy zapytasz | W chwili, gdy zajdzie zdarzenie |
| Obciążenie | Setki pustych zapytań „czy już?” | Jedno żądanie na realne zdarzenie |
| Świeżość informacji | Zależy od częstotliwości odpytywania | Niemal natychmiastowa |
| Wymaga | Dostępu do API nadawcy | Publicznego adresu po Twojej stronie |
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.
Webhooki bywają też alternatywą dla zadań cyklicznych. Zamiast uruchamiać crona, który co minutę sprawdza zmiany, pozwalasz, żeby zmiana sama wywołała akcję. Nie zawsze się da, ale gdy się da, jest czyściej.
Jak działa webhook krok po kroku
Cały cykl webhooka opiera się na jednym żądaniu HTTP i jednej odpowiedzi. Wygląda to skomplikowanie tylko na schemacie. W praktyce to kilka sekund i pięć etapów.
- 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.
- Wybierasz zdarzenie. Określasz, co ma uruchomić webhook: nowe zamówienie, zwrot płatności, dodanie produktu, zmiana statusu. Jedno zdarzenie to jeden wyzwalacz.
- Zachodzi zdarzenie. Klient płaci, formularz zostaje wysłany, repozytorium dostaje nowy commit. Serwer nadawcy zauważa to i przygotowuje paczkę danych.
- Nadawca wysyła żądanie POST. Na Twój adres trafia wiadomość HTTP z danymi zdarzenia, najczęściej w formacie JSON, czasem z podpisem w nagłówku.
- Twój serwer odpowiada. Skrypt odbiera dane, wykonuje swoją pracę i odsyła kod 200, czyli „dotarło, dziękuję”. Brak takiej odpowiedzi nadawca potraktuje jak nieudaną próbę.
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.
Gdzie spotkasz webhooki w praktyce
Webhooki najczęściej pracują w tle, dlatego rzadko zwracasz na nie uwagę, dopóki coś nie przestanie działać. A pracują w naprawdę wielu miejscach, z których korzystasz każdego dnia.
Płatności online to ich naturalne środowisko. Stripe, Przelewy24, PayU czy Tpay potwierdzają zaksięgowanie transakcji właśnie webhookiem. Twój sklep nie zgaduje, czy klient zapłacił. Dostaje powiadomienie i dopiero wtedy zmienia status zamówienia na opłacone, co jest bezpieczniejsze niż zaufanie samemu przekierowaniu z bramki.
W e-commerce webhooki spinają sklep z resztą układanki. Nowe zamówienie leci do hurtowni, do systemu fakturowego i do narzędzia kurierskiego naraz. W programowaniu GitHub czy GitLab wysyła webhook przy każdym wgraniu kodu, co uruchamia testy i wdrożenie. W komunikacji Slack i Discord przyjmują webhooki, żeby wrzucać powiadomienia na kanał.
Osobny, ogromny świat to automatyzacje bez kodu. Narzędzia w stylu Zapier, Make czy n8n zamieniają webhook w klocek, który łączysz z setkami aplikacji. Formularz na stronie wywołuje webhook, ten trafia do automatyzacji, a ona dodaje kontakt do bazy, wysyła powitalnego maila i powiadamia zespół. Więcej na ten temat znajdziesz w tekście o automatyzacjach z Zapier i Make.
Jak skonfigurować webhook w WooCommerce
WooCommerce ma webhooki wbudowane, więc nie potrzebujesz wtyczki ani programisty, żeby zacząć. Cała konfiguracja zajmuje kilka minut i sprowadza się do podania adresu oraz wyboru zdarzenia.
- Wejdź w ustawienia. W panelu WordPress przejdź do WooCommerce, potem Ustawienia, zakładka Zaawansowane i sekcja Webhooki. Kliknij „Dodaj webhook”.
- Nazwij i włącz. Wpisz czytelną nazwę, na przykład „Nowe zamówienie do hurtowni”, i ustaw status na Aktywny. Nazwa jest tylko dla Ciebie, więc niech będzie konkretna.
- Wybierz temat. W polu Temat wskaż zdarzenie, na przykład „Zamówienie utworzone” albo „Produkt zaktualizowany”. To ono uruchomi wysyłkę.
- Podaj adres dostarczenia. W polu Adres URL dostarczenia wklej endpoint odbiorcy, czyli adres systemu, który ma dostać dane. Musi działać po HTTPS.
- Ustaw sekret. Wpisz losowy, długi ciąg znaków jako Sekret. Posłuży do podpisania wiadomości, dzięki czemu odbiorca sprawdzi, że to naprawdę Twój sklep.
- Zapisz i przetestuj. Złóż testowe zamówienie i sprawdź w logu webhooka, czy wysyłka zakończyła się kodem 200. WooCommerce pokazuje historię dostarczeń przy każdym webhooku.
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.
Bezpieczeństwo webhooków
Skoro webhook to publiczny adres przyjmujący dane z zewnątrz, ktoś może spróbować wysłać tam fałszywe żądanie. Dlatego nigdy nie ufaj wiadomości tylko dlatego, że przyszła. Musisz potwierdzić, że nadał ją ten, za kogo się podaje.
Najważniejszym mechanizmem jest podpis. Nadawca liczy z treści wiadomości i wspólnego sekretu skrót, najczęściej algorytmem HMAC SHA-256, i wkłada go w nagłówek żądania. Ty po swojej stronie liczysz ten sam skrót i porównujesz. Jeśli się zgadza, wiadomość jest autentyczna i nie została zmieniona po drodze. Jeśli nie, odrzucasz ją bez zastanowienia.
Do tego dochodzi kilka nawyków, które warto wyrobić od początku.
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.
Jak testować i debugować webhooki
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.
Najczęstsze błędy przy webhookach
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.
Najczęściej zadawane pytania
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.
