Webhooki dla nietechnicznych: jak systemy 'gadają' ze sobą 

Ostatnia istotna aktualizacja: 28 października 2026. Co zmieniono: dodałem interaktywny symulator webhooka (wklejasz JSON i widzisz, co dostaje odbiorca), kalkulator „odpytywanie kontra webhook”, słowniczek, checklistę wdrożeniową i FAQ. Dopisałem to, czego brakowało: ponowienia wysyłki, limity czasu, podpisy, duplikaty i różnice między test a produkcja w n8n, wszystko na podstawie dokumentacji Stripe, GitHub, WooCommerce i n8n (lista na dole). Stare akapity o dzwonku do drzwi i płatnościach zostały, resztę przepisałem.

Webhook to wiadomość, którą jeden system sam wysyła do drugiego w chwili zdarzenia - np. gdy klient zapłaci albo ktoś wypełni formularz. Technicznie to żądanie HTTP POST z danymi w formacie JSON, wysłane na adres URL, który wcześniej podałeś. Zamiast pytać co minutę „czy coś się zmieniło?”, dostajesz znak dokładnie wtedy, gdy zmiana zaszła. Tak działa większość automatyzacji, które oszczędzają czas, nawet jeśli nigdy nie widziałeś tego słowa. Poniżej znajdziesz też symulator: wpisz własny JSON i zobacz, co dokładnie odbiera system po drugiej stronie.

Webhook bez żargonu: prosty obrazek

Wyobraź sobie dzwonek do drzwi zamiast pukania co kilka minut, żeby sprawdzić, czy ktoś przyszedł. Zwykłe sprawdzanie danych (tzw. odpytywanie API, ang. polling) działa jak to ciągłe pukanie: system pyta drugi system „masz coś nowego?” raz na minutę, raz na godzinę, bez względu na to, czy cokolwiek się zmieniło. Webhook odwraca zasadę. Ty podajesz swój adres (URL), a druga strona sama „dzwoni”, kiedy ma coś do przekazania.

Po Twojej stronie stoi mały skrypt albo automatyzacja, która odbiera tę wiadomość i coś z nią robi: zapisuje zamówienie, aktualizuje magazyn, wysyła e-mail albo dopisuje wiersz w arkuszu.

Ile pustych pytań oszczędza webhook (kalkulator)

Przesuń suwak, ile zdarzeń dziennie masz (np. zamówień), i wybierz, jak często system miałby pytać o nowości.

Przykład z domyślnych ustawień (20 zdarzeń dziennie, sprawdzanie co 5 minut): 288 zapytań na dobę, z czego co najmniej 268 pustych, a nowe zamówienie czeka średnio 2,5 minuty (najwyżej 5). Webhook to 20 wiadomości i opóźnienie liczone w sekundach (wyliczone).

Jak to wygląda krok po kroku

Załóżmy, że klient płaci za zamówienie w Twoim sklepie internetowym:

1. Operator płatności rejestruje wpłatę.
2. W tym samym momencie wysyła webhook - żądanie HTTP z danymi transakcji - na adres, który mu wcześniej podałeś.
3. Twój system (sklep, arkusz, automatyzacja w n8n) odbiera żądanie i sprawdza, czy pochodzi od właściwego nadawcy.
4. Odpowiada kodem 2xx (np. 200), czyli „mam, dziękuję”.
5. Zmienia status zamówienia, rezerwuje towar w magazynie i wysyła klientowi potwierdzenie.

Całość dzieje się w ciągu sekund, bez udziału człowieka i bez odświeżania panelu. Samo żądanie wygląda mniej więcej tak (uproszczony przykład, prawdziwi nadawcy mają własne pola):

POST /webhook/zamowienia HTTP/1.1
Content-Type: application/json
X-Signature-256: sha256=3f9c...

{
  "id": "evt_1001",
  "type": "payment.succeeded",
  "amount": 24900,
  "currency": "PLN",
  "customer": { "email": "anna@example.com" }
}

Symulator: co dokładnie odbiera Twój system

Wybierz gotowy przykład albo wpisz własny JSON, ustaw, czy nadawca podpisuje wiadomość i jak szybko Twój odbiorca odpowiada, i kliknij „Wyślij webhook”. Wszystko liczy się w Twojej przeglądarce, nic nie wychodzi do sieci. Sekret podpisu w demie to sekret-demo, a limit czasu (10 sekund) przyjąłem za dokumentacją GitHuba.

Co pokazuje symulator, w tekście

Dla trzech przykładów wynik jest zawsze podobny (obserwacja z samego symulatora):

• Poprawny JSON, podpis zgodny, odpowiedź w 1 sekundę: odbiorca zwraca 200 i widzisz listę pól z gotowymi wyrażeniami do n8n, np. {{ $json.body.customer.email }}.
• Ta sama wiadomość wysłana drugi raz: odbiorca rozpoznaje to samo id, odpowiada 200 i niczego nie przetwarza ponownie (ochrona przed duplikatem).
• Podpis zmieniony lub brakujący, a sprawdzanie włączone: odpowiedź 401, dane są odrzucone.
• Odbiorca odpowiada po ponad 10 sekundach: nadawca uznaje dostawę za nieudaną i ponowi ją, choć praca u Ciebie mogła się już wykonać. Dlatego ten sam webhook potrafi przyjść dwa razy.

Webhook a API - czym się różnią

Te dwa słowa często się mylą, choć robią coś przeciwnego. Przy klasycznym API to Ty pytasz: wysyłasz zapytanie i czekasz na odpowiedź, kiedy akurat chcesz sprawdzić dane. Przy webhooku role są odwrócone - to druga strona informuje Ciebie, dokładnie w chwili zdarzenia.

W realnych automatyzacjach obie metody się uzupełniają. Bramka płatności wysyła webhook „płatność zaksięgowana”, a Twój system odpytuje jej API, żeby pobrać pełne dane do faktury. Webhook daje sygnał, API dostarcza szczegóły. Stripe opisuje to wprost: nowsze, „cienkie” zdarzenia (thin events) niosą krótką informację, a pełny obiekt pobiera się osobnym zapytaniem do API (dokumentacja Stripe).

Gdzie w praktyce spotkasz webhooki

• Płatności online - operator płatności informuje sklep o zakończonej transakcji. Stripe wymienia jako typowy przypadek chwilę, w której bank klienta potwierdza płatność.
• Formularze kontaktowe i CRM - nowy lead trafia od razu do bazy klientów, bez przepisywania.
• WordPress i WooCommerce - sklep może wysyłać webhooki m.in. dla zamówień, klientów, produktów i kuponów; dostępne tematy zależą też od zainstalowanych wtyczek (dokumentacja WooCommerce).
• GitHub i narzędzia deweloperskie - każde zdarzenie w repozytorium może wywołać webhook (dokumentacja GitHub).
• Komunikatory i systemy monitorujące - wiadomość albo alert o awarii uruchamia dalszy proces w chwili zdarzenia, nie godzinę później.

Webhooki w n8n: automatyzacja bez pisania kodu

W n8n webhook to gotowy element: dodajesz go jako pierwszy krok automatyzacji i dostajesz unikalny adres URL, który wklejasz w drugim systemie (formularzu, CRM, sklepie). Od tego momentu każde zdarzenie uruchamia cały ciąg dalszych kroków: zapis do arkusza, powiadomienie na Slacku, odpowiedź wygenerowaną przez model językowy. Pierwszą taką automatyzację krok po kroku opisuję w poradniku Pierwsza automatyzacja w n8n, a wersję techniczną (lokalny test, ngrok, podpis HMAC) w tekście n8n webhook od zera.

Według dokumentacji węzła Webhook w n8n warto znać pięć rzeczy:

• Dwa adresy. Adres testowy działa, gdy klikniesz „Listen for Test Event” lub „Execute workflow” (dane widać w edytorze). Adres produkcyjny rejestruje się po opublikowaniu workflow, a jego przebiegi oglądasz w zakładce Executions. Najczęstsza pomyłka początkujących: wklejenie adresu testowego do systemu, który ma działać na stałe.
• Metody. Węzeł obsługuje DELETE, GET, HEAD, PATCH, POST i PUT.
• Uwierzytelnianie. Do wyboru: Basic auth, Header auth, JWT, n8n User Auth albo brak.
• Tryb odpowiedzi. Natychmiast („Workflow got started”), po zakończeniu ostatniego węzła albo przez węzeł Respond to Webhook. Do webhooków zewnętrznych, które ponawiają przy zwłoce, zwykle wystarczy odpowiedź natychmiastowa (opinia, wynika z reguły „najpierw 2xx, potem robota” opisanej niżej).
• Rozmiar. Maksymalny rozmiar ładunku to 16 MB, na własnym serwerze można go zmienić zmienną N8N_PAYLOAD_SIZE_MAX.

Nie trzeba pisać kodu - wystarczy poskładać gotowe klocki. Jedna taka automatyzacja potrafi zdjąć z zespołu kilka godzin ręcznej pracy tygodniowo (opinia na podstawie typowych wdrożeń, nie pomiar). Typowe pułapki zbieram w tekście 9 błędów w n8n, które kosztują najwięcej, a porównanie z innymi platformami znajdziesz w artykule n8n vs Make vs Zapier.

Na co zwrócić uwagę: bezpieczeństwo, duplikaty, ponowienia

Webhook to publiczny adres URL. Jeśli ktoś go zgadnie, może wysłać pod niego spreparowane dane. Stripe ostrzega, że bez weryfikacji atakujący mógłby wywołać akcje takie jak realizacja zamówień czy nadanie dostępu, i zaleca łączyć listę dozwolonych adresów IP z weryfikacją podpisu w nagłówku Stripe-Signature (Stripe). GitHub podpisuje dostawy kodem HMAC-SHA256 w nagłówku X-Hub-Signature-256 (wartość zaczyna się od sha256=) i radzi porównywać go funkcją o stałym czasie, a nie zwykłym == (GitHub). Podpis liczy się z niezmienionej treści żądania; jeśli framework przerobi treść, weryfikacja się nie uda.

Duplikaty i ponowienia. Nadawca ponawia wysyłkę, gdy nie dostanie szybkiej odpowiedzi 2xx. Stripe próbuje dostarczyć zdarzenie przez maksymalnie trzy dni z rosnącymi odstępami (tryb produkcyjny), a w trybie testowym trzy razy w ciągu kilku godzin. Zaleca też zapisywać identyfikatory już przetworzonych zdarzeń i nie przetwarzać ich drugi raz. GitHub oczekuje odpowiedzi 2xx w 10 sekund, a przy ponownym doręczeniu nagłówek X-GitHub-Delivery pozostaje taki sam jak w oryginale, więc nadaje się do rozpoznawania powtórek (GitHub). Kolejność zdarzeń też nie jest gwarantowana: Stripe pisze wprost, że nie ma gwarancji dostarczania ich w kolejności wygenerowania.

Poniższa tabela zestawia to, co dokumentacje faktycznie podają (pusta komórka znaczy: nie znalazłem w otwartej dokumentacji).

WooCommerce uznaje za błąd każdą odpowiedź inną niż 2xx, 301 lub 302 i wyłącza webhook po więcej niż pięciu błędach z rzędu (próg można zmienić filtrem woocommerce_max_webhook_delivery_failures). Wyłączony webhook ma status „Disabled”, a logi dostaw znajdziesz w WooCommerce > Status > Logs, źródło webhooks-delivery (WooCommerce). Praktyczny wniosek: pięć nieudanych dostaw z rzędu przy awarii serwera potrafi po cichu odciąć automatyzację, więc warto mieć alert (opinia).

Zasada, którą warto zapamiętać: najpierw szybka odpowiedź 2xx, potem właściwa praca w tle, a każde zdarzenie rozpoznawane po identyfikatorze. To zgodne z zaleceniami Stripe (zwrócić 2xx przed złożoną logiką) i GitHuba (odpowiedź w 10 sekund).

Checklista: czy Twój webhook jest gotowy do pracy

Odhaczaj punkty; stan zapisuje się w tej przeglądarce.

W skrócie, ta sama lista tekstem: adres HTTPS; weryfikacja podpisu na surowej treści; odpowiedź 2xx przed ciężką pracą; rozpoznawanie duplikatów po ID zdarzenia; brak zależności od kolejności; subskrypcja tylko potrzebnych typów zdarzeń; alert o nieudanych dostawach; w n8n adres produkcyjny zamiast testowego.

Kiedy sam webhook nie wystarczy

Webhook dobrze radzi sobie z prostym „coś się wydarzyło”. Gorzej, gdy dane trzeba przetworzyć, połączyć z inną bazą albo podjąć decyzję, np. ocenić, czy nowy lead jest wart telefonu. Wtedy webhook zostaje punktem wejścia, a logikę przejmuje automatyzacja z regułami albo model językowy. Jak połączyć kilka systemów w jeden przepływ, pokazuję w tekście Integracja sklepu, CRM i księgowości.

Zanim zaczniesz wdrażać cokolwiek samodzielnie, sprawdź, który proces w firmie generuje najwięcej powtarzalnej ręcznej pracy. To zwykle najlepszy kandydat na pierwszy webhook. Jeśli chcesz to przegadać na przykładzie z Twojej firmy, napisz do mnie.

Słowniczek

Webhook

Automatyczne żądanie HTTP wysyłane przez system A do systemu B w chwili zdarzenia.

Endpoint (punkt końcowy)

Adres URL, który odbiera webhooki. W n8n generuje go węzeł Webhook.

Payload (ładunek)

Treść wiadomości, zwykle JSON z danymi zdarzenia.

JSON

Tekstowy format danych: pary „nazwa: wartość” w nawiasach klamrowych, np. {"email": "anna@example.com"}.

POST

Metoda HTTP służąca do wysyłania danych na serwer; najczęstsza w webhookach.

Kod odpowiedzi 2xx

Odpowiedź „przyjęto” (np. 200). Nadawcy traktują ją jako potwierdzenie dostawy.

Nagłówek (header)

Dodatkowa informacja dołączona do żądania, np. typ treści albo podpis.

Sekret / podpis (HMAC)

Wspólne hasło i skrót z treści wiadomości, który pozwala sprawdzić, że nadawca jest autentyczny, a treść nie została zmieniona.

Replay (powtórzenie ataku)

Ponowne wysłanie przechwyconej, prawdziwej wiadomości. Stripe broni się znacznikiem czasu w podpisie i domyślną tolerancją 5 minut.

Retry (ponowienie)

Ponowna próba dostawy po nieudanej pierwszej.

Idempotentność

Cecha obsługi, dzięki której wielokrotne przetworzenie tego samego zdarzenia daje taki sam skutek jak jednokrotne (np. zamówienie zapisane raz).

Timeout

Limit czasu oczekiwania na odpowiedź; po jego przekroczeniu dostawa jest uznana za nieudaną.

Polling (odpytywanie)

Cykliczne pytanie systemu o nowe dane, odwrotność webhooka.

Adres testowy i produkcyjny (n8n)

Test działa podczas ręcznego nasłuchiwania w edytorze, produkcyjny po opublikowaniu workflow.

FAQ: najczęstsze pytania o webhooki

Źródła

1. Stripe: Receive Stripe events in your webhook endpoint - ponowienia (do 3 dni, produkcja), duplikaty, kolejność, podpis Stripe-Signature, tolerancja 5 minut, szybkie 2xx. Dokumentacja pierwotna, otwarta 28.10.2026.
2. GitHub: Best practices for using webhooks - odpowiedź 2xx w 10 sekund, X-GitHub-Delivery, HTTPS. Dokumentacja pierwotna, otwarta 28.10.2026.
3. GitHub: Validating webhook deliveries - X-Hub-Signature-256, HMAC SHA-256, porównanie w stałym czasie. Dokumentacja pierwotna, otwarta 28.10.2026.
4. WooCommerce: Webhooks - statusy, wyłączanie po więcej niż pięciu błędach z rzędu, logi dostaw. Dokumentacja pierwotna, otwarta 28.10.2026.
5. n8n: Webhook node - adres testowy i produkcyjny, metody, uwierzytelnianie, tryby odpowiedzi, limit 16 MB. Dokumentacja pierwotna, otwarta 28.10.2026.

Etykiety siły twierdzeń: wyliczone - wynik arytmetyki z podanych danych; obserwacja - zachowanie symulatora na tej stronie; opinia - moja ocena, nie pomiar. Symulator jest uproszczonym modelem, nie kopią żadnego konkretnego nadawcy.