Webhook

Mechanizm, w którym jedna usługa automatycznie wysyła powiadomienie HTTP do innej po wystąpieniu zdarzenia. Działa odwrotnie niż klasyczne odpytywanie API.

Webhook to mechanizm, w którym jedna usługa sama z siebie wysyła żądanie HTTP (najczęściej POST) pod adres wskazany przez Ciebie, gdy tylko wydarzy się coś, co Cię interesuje. Zamiast co kilka sekund pytać serwer „no co, jest już płatność? a teraz? a teraz?”, podajesz mu swój URL i mówisz „daj znać, jak będzie”. To dlatego webhooki bywają nazywane reverse API albo HTTP push — dane lecą do Ciebie, a nie Ty po nie.

Jak to działa

Konfiguracja sprowadza się do jednego: rejestrujesz w danej usłudze endpoint, czyli publiczny adres swojego serwera, np. https://twojadomena.pl/webhooki/stripe. Od tej chwili, gdy zajdzie zdarzenie (klient zapłacił, ktoś zrobił push do repo, przyszła nowa wiadomość), usługa pakuje opis zdarzenia w JSON i wysyła go na ten adres. Twoja aplikacja odbiera żądanie, czyta payload i robi swoje — aktualizuje zamówienie, odpala build, wysyła powiadomienie.

Kluczowa różnica względem klasycznego pollingu: przy odpytywaniu marnujesz zasoby na setki zapytań, z których większość zwraca „nic nowego”. Webhook odzywa się dokładnie wtedy, gdy jest po co — szybciej i taniej. Cena za to jest taka, że Twój endpoint musi być dostępny z internetu i gotowy odebrać ruch w każdej chwili.

Przykład z praktyki

Klasyk to GitHub i pipeline CI/CD. Ustawiasz webhook na zdarzenie push, GitHub po każdym wypchnięciu kodu uderza POST w Twój serwer, a ten odpala testy i deploy. Drugi klasyk to Stripe — po udanej płatności dostajesz zdarzenie checkout.session.completed i dopiero wtedy odblokowujesz dostęp do produktu.

Żeby testować webhooki lokalnie (bo localhost nie jest widoczny z internetu), używa się tunelu. Stripe ma własne CLI:

stripe listen --forward-to localhost:4242/webhook

Częste błędy

  • Brak weryfikacji podpisu. Skoro endpoint jest publiczny, każdy może w niego strzelić sfałszowanym żądaniem. Sprawdzaj nagłówek z sygnaturą (np. Stripe-Signature) i sekret — inaczej ktoś „zaliczy” Ci płatność, której nie było.
  • Założenie, że zdarzenie przyjdzie raz. Większość dostawców gwarantuje at-least-once delivery, czyli to samo zdarzenie może dotrzeć kilka razy. Obsługa musi być idempotentna — zwykle po unikalnym id zdarzenia.
  • Wolna odpowiedź. Jeśli nie odpowiesz kodem 2xx w kilka sekund, dostawca uzna to za błąd i będzie ponawiał. Ciężką robotę wrzucaj do kolejki, a od razu zwracaj 200.

Pojęcia powiązane: polling, REST API, endpoint, payload, idempotency, webhook secret, kolejka zadań, callback URL.