Webhook to notyfikacja HTTP, którą serwer pushuje na URL skonfigurowany przez klienta, gdy tylko zajdzie zdarzenie: otrzymana płatność (Stripe), wepchnięty commit (GitHub), wypełniony formularz (Typeform), wystawiona faktura (Stripe), odebrana wiadomość (Slack). To lustro REST API: zamiast pytać „co nowego?” w pętli (*polling*), serwer mówi „oto co się właśnie wydarzyło” dokładnie w tym momencie. Payloadem jest niemal zawsze POST JSON na podany przez Państwa endpoint.
Webhook eliminuje latencję i niepotrzebne zużycie pollingu. Skrypt odpytujący API Stripe co minutę, by sprawdzić nową płatność, to 1 440 wywołań/dzień na próżno w 99 % przypadków — webhook robi 1 wywołanie w momencie płatności i koniec. Dlatego spotyka się je wszędzie: w CRM powiadamiającym ERP o wygranym dealu, w PIM synchronizującym zmianę ceny do Shopify, w narzędziach biznesowych reagujących na zdarzenia z budownictwa/zdrowia/finansów. To także element spinający klocki stacka low-code (n8n, Make, Zapier).
Trzy rzeczy decydują o tym, czy webhook działa, czy kładzie produkcję: podpis HMAC (weryfikacja, że payload pochodzi od nadawcy, a nie atakującego spamującego publiczny URL), idempotentność (to samo zdarzenie może przyjść dwa razy — handler musi je zignorować, jeśli już obsłużone, przez `event_id`) i wykładniczy retry po stronie nadawcy (Stripe ponawia przez 3 dni, jeśli serwer leży). W architekturach z dużą liczbą zdarzeń wewnętrznych lub potrzebami fan-out wskakujemy na poziom wyżej, do prawdziwej architektury event-driven z Kafka lub NATS zamiast webhooków point-to-point.
Webhook: 4 zasady do zachowania
- Systematyczny podpis HMAC: bez weryfikacji każdy może wysłać fałszywe płatności na endpoint.
- Idempotentność przez `event_id`: zapisywać już obsłużone ID, ignorować duplikaty — Stripe może wysłać 2-3 razy.
- Szybka odpowiedź (poniżej 5 s): przetwarzać w tle, odpowiedzieć 200 natychmiast — inaczej timeout i retry.
- Logi otrzymanych payloadów: niezbędne, by zdebugować zgubione zdarzenie 3 dni później.
