Twoja aplikacja nie musi co minutę pytać zewnętrznej usługi, czy coś się zmieniło. Może udostępnić adres, pod który ta usługa wyśle informację po wystąpieniu zdarzenia. Tak działa webhook: odwraca kierunek inicjowania komunikacji i pozwala reagować bez ciągłego odpytywania.
Najłatwiej zobaczyć ten mechanizm na małym przykładzie. Uruchomimy lokalny odbiornik oraz skrypt udający usługę, która informuje o zakończeniu budowania aplikacji. Potem przejdziemy do rzeczy, których sama demonstracja nie rozwiązuje: potwierdzania nadawcy, ponowień i zdarzeń otrzymanych więcej niż raz.
Webhook, czyli powiadomienie wysłane do twojej aplikacji
W typowej integracji wybierasz zdarzenia, które cię interesują, i podajesz adres odbiornika. Kiedy wystąpi takie zdarzenie, system źródłowy wysyła żądanie HTTP z jego danymi. Twój endpoint, czyli punkt obsługi pod konkretnym adresem, odbiera wiadomość i decyduje, co zrobić dalej.
Na przykład GitHub może powiadomić inną aplikację o zmianie w repozytorium. Odbiornik może wtedy uruchomić zadanie, zapisać informację lub wysłać komunikat. Zasadę subskrybowania zdarzeń opisuje wprowadzenie do webhooków GitHub.
Sam webhook nie jest całą automatyzacją. Jest sposobem przekazania sygnału. Reguła „po otrzymaniu zdarzenia utwórz zadanie” należy już do logiki odbiorcy. Możesz napisać ją w kodzie albo zbudować w narzędziu obsługującym takie wyzwalacze.
Webhook a polling i zwykłe wywołanie API
Przy pollingu twoja aplikacja regularnie pyta usługę o aktualny stan. Przy webhooku to usługa inicjuje dostarczenie informacji o zmianie. Różnica dotyczy sposobu komunikacji, a nie magicznego zastąpienia API inną technologią: webhook sam zwykle korzysta z HTTP.
| Podejście | Kto zaczyna komunikację | Przykład |
|---|---|---|
| Jednorazowe wywołanie API | Twoja aplikacja | Pobranie szczegółów jednego zadania na żądanie użytkownika |
| Polling | Twoja aplikacja, cyklicznie | Sprawdzanie statusu zadania co minutę |
| Webhook | System, w którym wystąpiło zdarzenie | Powiadomienie o zakończeniu zadania |

Polling nadal ma zastosowanie, gdy usługa nie udostępnia potrzebnego webhooka albo wystarczy okazjonalne odświeżenie danych. W praktyce oba podejścia mogą współpracować: webhook sygnalizuje zmianę, a API służy do pobrania szczegółów lub okresowego uzgodnienia stanu.
Nie traktuj powiadomienia jako gwarancji natychmiastowej dostawy. Po drodze są sieć, serwery i kolejki. Integracja musi wiedzieć, co zrobić również wtedy, gdy wiadomość przyjdzie później albo nie uda się jej odebrać.
Co zawiera żądanie webhooka
W naszym przykładzie nadawca wyśle POST pod /webhook, z nagłówkiem Content-Type: application/json. Treść, nazywana payloadem, będzie zawierała identyfikator i typ zdarzenia oraz wynik zadania.
To umówiony format demonstracyjny, a nie standard obowiązujący we wszystkich usługach. W prawdziwej integracji sprawdzasz dokumentację nadawcy: metodę, adres, nagłówki, strukturę danych i sposób weryfikacji.

Nie wystarczy zaakceptować dowolnego poprawnego JSON-a. Odbiornik powinien sprawdzić, czy dostał oczekiwany typ zdarzenia i potrzebne pola. Tablica, liczba albo obiekt z innymi kluczami też mogą być poprawnym JSON-em, lecz nie pasują do kontraktu twojej integracji.
Do czytania przykładowego body i sprawdzenia składni przydaje się formatter JSON. Nie wklejaj do udostępnianych przykładów tokenów ani danych prawdziwych użytkowników.
Prosty przykład webhooka w Pythonie
Potrzebujesz Pythona 3 i dwóch terminali. Nie instalujemy dodatkowych bibliotek. Utwórz pusty katalog, w którym zapiszesz trzy pliki: receiver.py, event.json oraz send_event.py.
To demonstracja wyłącznie na własnym komputerze. Odbiornik nasłuchuje na 127.0.0.1, nie sprawdza podpisu nadawcy i nie przechowuje zdarzeń w bazie. Nie wystawiaj go publicznie jako gotowej integracji. Dokumentacja Pythona wprost nie zaleca http.server do zastosowań produkcyjnych.
1. Utwórz odbiornik
Zapisz w receiver.py:
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
class Receiver(BaseHTTPRequestHandler):
def reply(self, status, message):
body = json.dumps(message).encode("utf-8")
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_POST(self):
if self.path != "/webhook":
return self.reply(404, {"error": "wrong_path"})
if self.headers.get_content_type() != "application/json":
return self.reply(415, {"error": "use_json"})
try:
size = int(self.headers.get("Content-Length", "0"))
except ValueError:
return self.reply(400, {"error": "invalid_length"})
if not 0 < size <= 65536:
return self.reply(413, {"error": "invalid_size"})
try:
event = json.loads(self.rfile.read(size))
except (ValueError, UnicodeError):
return self.reply(400, {"error": "invalid_json"})
if not isinstance(event, dict):
return self.reply(400, {"error": "expected_object"})
if (
not isinstance(event.get("id"), str)
or not event["id"]
or event.get("type") != "build.finished"
or event.get("status") not in ("success", "failed")
):
return self.reply(400, {"error": "invalid_event"})
print(json.dumps(event), flush=True)
self.reply(200, {"received": event["id"]})
if __name__ == "__main__":
print("Local demo: http://127.0.0.1:8765/webhook", flush=True)
HTTPServer(("127.0.0.1", 8765), Receiver).serve_forever()
Program przyjmuje tylko wskazaną ścieżkę, format JSON i treść o rozmiarze do 65 536 bajtów. Następnie sprawdza podstawowe pola, wypisuje zdarzenie w terminalu i zwraca potwierdzenie. To cała wykonywana tutaj operacja. Nie powstaje żaden wpis w zewnętrznej usłudze.
W pierwszym terminalu uruchom:
python receiver.py
Jeżeli w twoim systemie Python 3 jest dostępny jako python3 lub py, użyj odpowiedniej nazwy w obu poleceniach uruchomienia. Pozostaw terminal otwarty. Zatrzymasz serwer skrótem Ctrl+C.
2. Przygotuj przykładowe zdarzenie
Plik event.json powinien zawierać:
{
"id": "evt_123",
"type": "build.finished",
"project": "moja-aplikacja",
"status": "success"
}
id identyfikuje zdarzenie, a nie sam projekt. type mówi, co się wydarzyło. status jest wynikiem budowania. Pole project ułatwia czytanie przykładu; nasz odbiornik nie wykorzystuje go do podejmowania decyzji.
3. Wyślij żądanie
Zapisz obok plik send_event.py:
from pathlib import Path
from urllib.request import Request, urlopen
body = Path(__file__).with_name("event.json").read_bytes()
request = Request(
"http://127.0.0.1:8765/webhook",
data=body,
headers={"Content-Type": "application/json"},
method="POST",
)
with urlopen(request, timeout=5) as response:
print(response.status, response.read().decode("utf-8"))
Używamy urllib.request z biblioteki standardowej, aby wysłać zawartość pliku jako żądanie HTTP. W drugim terminalu, w tym samym katalogu, wykonaj:
python send_event.py
Przy działającym odbiorniku i powyższych danych otrzymasz:
200 {"received": "evt_123"}
W pierwszym terminalu zobaczysz odebrany obiekt JSON oraz log żądania. Nadawca i odbiorca są tu dwoma programami na jednej maszynie. W rzeczywistej integracji skrypt nadawczy zastępuje usługa, która uruchamia wysyłkę po swoim zdarzeniu.
4. Sprawdź błąd i powtórzenie
Zmień status na unknown i ponów wysyłkę. Odbiornik zwróci 400, a skrypt wysyłający zgłosi HTTPError. To oczekiwane: klient z tego przykładu nie ma jeszcze rozbudowanej obsługi błędów.
Przywróć success i uruchom nadawcę dwa razy. Zobaczysz dwa potwierdzenia oraz dwa wpisy odbiornika z tym samym evt_123. Nasz program nie usuwa duplikatów. Wypisanie powtórnego logu nie szkodzi, ale dwukrotne wykonanie operacji biznesowej mogłoby już być problemem.
Jeśli dostajesz błąd połączenia zamiast odpowiedzi HTTP, sprawdź, czy pierwszy terminal nadal działa i czy oba pliki używają portu 8765. Otwarcie adresu w przeglądarce wysyła zwykle GET, a program obsługuje POST; nie jest to równoważny test.
Ten sam mechanizm możesz wykorzystać w przepływie n8n. Do prób przygotowałem konfigurację z importowalnym workflow i Header Auth.
Dlaczego odpowiedź 200 nie rozwiązuje całej integracji
Nadawca potrzebuje odpowiedzi, aby ocenić dostarczenie żądania. To, jaki status uznaje za sukces i jak długo czeka, zależy od usługi. GitHub oczekuje odpowiedzi 2xx w ciągu 10 sekund, co opisuje w dobrych praktykach webhooków.
Długie zadanie nie powinno blokować połączenia przez kilka minut. W większej aplikacji odbiornik weryfikuje wiadomość, trwale zapisuje ją lub umieszcza w trwałej kolejce i potwierdza przyjęcie. Osobny proces wykonuje właściwą pracę. Potwierdzenie oznacza wtedy odpowiedzialność za dalszą obsługę, a niekoniecznie zakończenie zadania.
Nie wysyłaj sukcesu, jeśli wiadomość istnieje wyłącznie w ulotnej pamięci procesu, a jej utrata jest niedopuszczalna. Awaria tuż po odpowiedzi może sprawić, że nadawca uzna dostawę za udaną, choć operacja nigdy nie zostanie wykonana.
Nasza demonstracja świadomie nie ma kolejki. Sukces oznacza tylko, że dane zostały zaakceptowane i wypisane w terminalu. Nie przedstawia trwałego przetwarzania ani gwarancji dostarczenia.
Powtórzenia, kolejność i idempotencja
Wyobraź sobie, że odbiornik zapisał zadanie, ale odpowiedź zaginęła w sieci. Nadawca widzi błąd i może spróbować ponownie. Dlatego nie należy utożsamiać jednego zdarzenia z dokładnie jednym żądaniem.
Idempotentna obsługa oznacza, że ponowne przetworzenie tej samej operacji nie wywoła drugiego niezamierzonego skutku. Przykładowo zdarzenie evt_123 nie powinno dwa razy utworzyć tego samego zadania w systemie docelowym.

W aplikacji produkcyjnej rejestr obsłużonych identyfikatorów powinien być trwały. Trzeba też rozwiązać wyścig: dwa procesy mogą jednocześnie stwierdzić, że identyfikator jeszcze nie istnieje. Pomagają ograniczenia unikalności, transakcje i mechanizmy idempotencji systemu, w którym wykonujesz operację. Sam warunek w pamięci jednego procesu nie wystarczy dla całego wdrożenia.
Nie zakładaj również kolejności zgodnej z momentem powstania zdarzeń. Stripe opisuje zarówno możliwe duplikaty, jak i brak gwarancji kolejności w swojej dokumentacji webhooków. Jeśli otrzymasz informację o późniejszym stanie przed wcześniejszym, nie powinieneś bez sprawdzenia cofać aktualnych danych.
Zasady retry nie są wspólne dla wszystkich dostawców. GitHub nie ponawia automatycznie nieudanych dostarczeń: przewiduje mechanizmy sprawdzania i ponownego wysyłania opisane w obsłudze nieudanych webhooków. Przed wdrożeniem ustal politykę konkretnej usługi oraz sposób odzyskania pominiętych zdarzeń.
Jak sprawdzić, kto naprawdę wysłał webhook
Publiczny adres odbiornika może wywołać również ktoś inny niż oczekiwana usługa. Sama znajomość URL-a i poprawny JSON nie potwierdzają nadawcy. HTTPS chroni transmisję, ale nie zastępuje weryfikacji autentyczności wiadomości.
GitHub wykorzystuje sekret webhooka oraz HMAC-SHA256 przesyłany w X-Hub-Signature-256. Odbiornik oblicza oczekiwaną wartość dla otrzymanej treści i porównuje ją w sposób odporny na ataki czasowe. Należy zrobić to przed uruchomieniem logiki biznesowej, zgodnie z instrukcją weryfikacji podpisu GitHub.
To przykład konkretnego dostawcy, nie nazwa uniwersalnego nagłówka webhooków. Stripe używa Stripe-Signature i własnych reguł walidacji; najlepiej korzystać z oficjalnej biblioteki. Zachowaj oryginalną treść żądania, ponieważ jej przekształcenie przed sprawdzeniem podpisu może zmienić wynik.
Sekret przechowuj poza repozytorium i nie dopisuj go do URL-a ani logów. Weryfikacja podpisu, kontrola świeżości tam, gdzie wspiera ją dostawca, oraz rozpoznawanie powtórzeń rozwiązują powiązane, ale różne problemy.
Od localhost do działającej integracji
Adres 127.0.0.1 wskazuje maszynę, która go używa. Zewnętrzna usługa nie połączy się w ten sposób z twoim laptopem. Potrzebujesz dostępnego dla niej endpointu HTTPS albo narzędzia testowego, które bezpiecznie przekazuje zdarzenia do środowiska lokalnego.
Publiczny odbiornik możesz utrzymywać na własnym serwerze. Wtedy dochodzą certyfikat, reverse proxy, kontrola dostępu, logi i monitorowanie. Podstawy wyboru infrastruktury opisuje artykuł czym jest VPS. Jeśli aplikację pakujesz w kontener, zobacz również jak działa Docker; kontener sam nie zapewnia autentyczności zdarzeń.
Przed uruchomieniem integracji sprawdź poprawne zdarzenie, nieprawidłowy podpis, ponowne dostarczenie, awarię odbiornika i błąd wykonywanego zadania. Loguj identyfikator oraz wynik obsługi, ale ogranicz zapisywanie prywatnych danych z payloadu. Dzięki temu da się odpowiedzieć na konkretne pytanie: czy wiadomość nie dotarła, została odrzucona, czy dotarła i nie udało się jej przetworzyć?
Gdy żądanie nie dociera do procesu, oddziel odmowę połączenia od błędu 502 na reverse proxy. Stan i logi serwera sprawdzisz poleceniami ze ściągi Nginx.
Najczęstsze pytania
Czy webhook to to samo co API?
Nie. Webhook opisuje sposób informowania odbiorcy o zdarzeniu, zwykle przez wywołanie jego endpointu HTTP. API jest szerszym interfejsem komunikacji. Jedna integracja może otrzymywać webhooki i dodatkowo pobierać dane przez API.
Dlaczego webhook nie działa na localhost?
Zewnętrzny nadawca nie widzi twojego localhost. Ten adres oznacza własną maszynę nadawcy, a nie twój komputer. Lokalny przykład działa dlatego, że odbiornik i skrypt wysyłający uruchamiasz na tej samej maszynie.
Dlaczego dostaję to samo zdarzenie kilka razy?
Może chodzić o ponowienie po błędzie lub niejednoznacznym wyniku dostawy. Sprawdź identyfikatory i politykę nadawcy. Odbiornik powinien rozpoznawać duplikaty i nie wykonywać drugi raz operacji, która ma wystąpić tylko raz.
Jaki kod HTTP powinien zwracać webhook?
Zwracaj status zgodny z kontraktem usługi i faktycznym wynikiem przyjęcia wiadomości. W naszej demonstracji poprawne zdarzenie kończy się 200, a błędna struktura 400. Nie kopiuj tych zasad bez sprawdzenia wymagań konkretnego dostawcy.
Czy do webhooka trzeba mieć własny serwer?
Nie zawsze. Odbiornikiem może być funkcja w chmurze lub narzędzie automatyzacji udostępniające odpowiedni adres. Nadal trzeba skonfigurować uwierzytelnianie, rozumieć format zdarzenia i zadbać o obsługę błędów.
Źródła
- About webhooks, GitHub.
- Best practices for using webhooks, GitHub.
- Validating webhook deliveries, GitHub.
- Handling failed webhook deliveries, GitHub.
- Receive Stripe events in your webhook endpoint, Stripe.
- http.server: HTTP servers, Python Software Foundation.
- urllib.request: opening URLs, Python Software Foundation.
Data publikacji: 30.09.2026.

Dyskusja