Webhook

Mechanizm asynchronicznego powiadamiania przez HTTP — gdy zdarzenie zajdzie na serwerze, serwer wysyła POST do zdefiniowanego URL-a z danymi zdarzenia — zamiast klient musiał regularnie odpytywać API. Fundament asynchronicznej architektury agentów przy długotrwałych zadaniach.

W Polsce nazywane też:

webhookpowiadomienie HTTPwywołanie zwrotne HTTPevent callback

Standardowe API jest jak pytanie i odpowiedź. Ty pytasz, serwer odpowiada. Ale co jeśli chcesz żeby serwer powiedział ci gdy coś się wydarzy — nowe zamówienie, zmiana statusu, nowy komentarz — bez żebyś co minutę pytał „czy coś nowego?”

Polling — regularne odpytywanie API — jest nieefektywny: większość zapytań zwróci „nic nowego” i zmarnuje zasoby. Webhook rozwiązuje to przez odwrócenie kierunku komunikacji.

Czym jest webhook

Webhook to mechanizm asynchronicznego powiadamiania przez HTTP — gdy zdarzenie zajdzie na serwerze (nowe zamówienie, zmiana statusu, otrzymana wiadomość), serwer sam wysyła żądanie HTTP POST do zdefiniowanego URL-a z danymi zdarzenia — zamiast klient musiał regularnie odpytywać API czy coś nowego się wydarzyło.

Webhooks w architekturze agentów

Agenty AI które działają asynchronicznie — uruchamiają długotrwałe procesy, czekają na zewnętrzne zdarzenia — naturalnie korzystają z webhooków. Agent zleca zadanie zewnętrznemu serwisowi i podaje webhook URL do powiadomienia gdy zadanie jest gotowe. Zamiast agent poll’uje co sekundę „czy gotowe?” — serwis odpala webhook gdy skończy.

Przykład w A2A: agent orchestrujący zleca zadanie agentowi-workerowi z asynchronicznym Task. Worker podaje webhook URL jako endpoint dla statusu. Gdy worker skończy, webhook informuje orchestratora — bez utrzymywania połączenia przez cały czas trwania zadania.

Bezpieczeństwo webhooków

Webhook endpoint jest publicznie dostępnym URL-em który przyjmuje POST requesty. Każdy kto zna URL może wysłać fałszywy event. Właściwa implementacja wymaga: weryfikacji podpisu (HMAC-SHA256 z shared secret), walidacji źródła IP (jeśli dostawca publikuje listę IP), i idempotentności (obsługa duplikatów — ten sam event może dotrzeć dwa razy).

Bez weryfikacji podpisu webhook jest wektorem ataku — atakujący może wysłać fałszywe zdarzenia które agent przetworzy jako prawdziwe.

Webhooks a MCP

MCP serwerresy które obsługują długotrwałe operacje mogą używać webhooków jako mechanizmu notyfikacji. Agent wywołuje narzędzie MCP, narzędzie uruchamia asynchroniczny proces i zwraca „pending” z webhook URL. Gdy proces się kończy — webhook informuje agenta który może pobrać wynik.

Alternatywą jest SSE streaming — agent utrzymuje połączenie i dostaje updates w czasie rzeczywistym. Webhook jest lepszy gdy zadanie trwa długo (minuty, godziny) i utrzymywanie połączenia przez cały czas jest nieefektywne.

Powiązane pojęcia

Zdarzenia wysyłane przez serwerStandard W3C umożliwiający serwerowi wysyłanie strumienia danych do klienta przez długotrwałe połączenie HTTP — powszechnie używany do streamingu odpowiedzi modeli AI (token po tokenie) i jako transport MCP (deprecjonowany od wersji 2025-03-26 na rzecz Streamable HTTP).Pętla agentaPodstawowy cykl działania autonomicznego agenta AI — powtarzająca się sekwencja percepcji, planowania, akcji i oceny wyniku — która kontynuuje się aż agent osiągnie cel lub zostanie zatrzymany. Fundament architektoniczny każdego agenta który działa wielokrokowo.Protokół agent-agentOtwarty protokół ogłoszony przez Google w kwietniu 2025 roku umożliwiający autonomicznym agentom AI wzajemne odkrywanie się, delegowanie zadań i koordynowanie pracy bez pośrednictwa człowieka — komplementarny z MCP, który obsługuje połączenia agent-narzędzie.Protokół kontekstu modeluOtwarty standard Anthropic umożliwiający agentom AI łączenie się z zewnętrznymi narzędziami, bazami danych i API w ustandaryzowany sposób — jak USB dla modeli językowych.