Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Webhook: co to jest i jak działa na prostym przykładzie

Dzwonek zdarzenia i koperta lecąca do otworu odbiornika na fioletowym tle

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 jako powtarzane pytania odbiorcy i webhook jako wiadomość wysłana przez usługę po zdarzeniu
Polling regularnie pyta o zmianę, a webhook przekazuje wiadomość po zdarzeniu.

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.

Schemat żądania POST z nagłówkiem Content-Type i treścią zdarzenia JSON
Żądanie webhooka zawiera adres i metodę, nagłówki oraz treść zdarzenia.

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.

Dwa komunikaty evt_123 trafiają do sprawdzenia, czy zdarzenie zostało już obsłużone
Powtórna dostawa tego samego zdarzenia nie powinna powtarzać wykonanej operacji.

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

Data publikacji: 30.09.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *