Czym jest webhook? Jak aplikacje wysyłają sobie powiadomienia

Webhook to automatyczna wiadomość, którą jedna usługa wysyła do Twojej aplikacji w chwili, gdy coś się wydarzy. Gdy płatność klienta się powiedzie, Stripe wysyła webhook na adres w Twojej aplikacji z informacją „płatność zakończona sukcesem, oto szczegóły”, a aplikacja reaguje — oznacza zamówienie jako opłacone, wysyła potwierdzenie, odblokowuje konto. Krótko mówiąc: API to pytanie, które Twoja aplikacja zadaje innej usłudze; webhook to wezwanie, w którym inna usługa dzwoni do Twojej aplikacji, by coś zakomunikować.

Dlaczego to ma znaczenie przy budowaniu z AI

Jak tylko Twoja aplikacja przyjmuje płatności, odbiera zgłoszenia z innego narzędzia albo łączy się z usługami takimi jak GitHub, Shopify czy kalendarz, natrafisz na webhooki. To zwykle właściwy sposób, by dowiedzieć się, że coś się stało — ale też miejsce, w którym aplikacje budowane przez AI najczęściej są po cichu błędne:

• Endpoint przyjmuje dowolne żądanie, więc każdy może podrobić zdarzenie „płatność zakończona sukcesem”.
• Aplikacja przyznaje dostęp na stronie przekierowania po płatności zamiast w webhooku, więc osoby, które zamkną kartę za wcześnie, nie dostają tego, za co zapłaciły, a ci, którzy znajdą adres strony sukcesu, dostają wszystko za darmo.
• To samo zdarzenie dociera dwukrotnie i klient dostaje dwa zamówienia albo dwa e-maile.

Znajomość działania webhooków pozwala poprosić o zabezpieczenia z wyprzedzeniem.

Codzienna analogia: SMS od kuriera

Możesz dowiedzieć się, że paczka dotarła, na dwa sposoby. Możesz co dziesięć minut chodzić do drzwi i sprawdzać (to odpytywanie — polling — gdy Twoja aplikacja wielokrotnie wywołuje API, by zapytać „coś nowego?”). Albo kurier może wysłać Ci SMS, że doręczył paczkę (to webhook).

SMS jest wyraźnie lepszy — o ile możesz mu ufać. Gdyby ktokolwiek mógł wysłać Ci wiadomość „paczka doręczona”, chciałbyś mieć sposób, by sprawdzić, czy naprawdę przyszła od kuriera. A gdyby telefon był wyłączony, gdy przyszedł SMS, chciałbyś, żeby kurier spróbował ponownie później. Te dwie kwestie — weryfikacja i ponowienia — stanowią większość trudności związanych z webhookami.

Jak działa webhook, krok po kroku

1. Tworzysz endpoint w backendzie aplikacji: adres, na przykład https://yourapp.com/webhooks/stripe, który przyjmuje żądania POST.
2. Rejestrujesz ten adres u dostawcy i wybierasz zdarzenia, które Cię interesują (np. „checkout zakończony” i „subskrypcja anulowana”).
3. Dostawca daje Ci sekret podpisu. Zapisujesz go jako sekret na serwerze — zobacz zmienne środowiskowe i sekrety.
4. Zdarzenie się wydarza. Dostawca wysyła żądanie HTTP na Twój adres z treścią JSON opisującą zdarzenie oraz nagłówkiem z podpisem.
5. Aplikacja weryfikuje podpis, zapisuje identyfikator zdarzenia, szybko odpowiada kodem sukcesu (200), a dopiero potem wykonuje pracę.
6. Jeśli aplikacja nie odpowie sukcesem, wielu dostawców ponawia próbę później.

Podpisy

Podpis dowodzi, że żądanie pochodzi od dostawcy i nie zostało zmienione. Stripe na przykład oblicza HMAC (rodzaj klucza-odcisku palca) z użyciem SHA-256, na podstawie treści żądania i znacznika czasu, przy użyciu sekretu podpisu, i wysyła go w nagłówku Stripe-Signature. Twoja aplikacja wykonuje to samo obliczenie ze swoją kopią sekretu; jeśli wyniki się zgadzają, żądanie jest prawdziwe. Ponieważ znacznik czasu też jest podpisany, możesz odrzucić stare żądania, które ktoś nagrał i odtwarza później — biblioteki Stripe domyślnie tolerują pięć minut, według dokumentacji stanu z września 2026.

Jeden praktyczny szczegół: podpis liczy się z surowej treści żądania. Jeśli Twój framework parsuje i formatuje JSON przed weryfikacją, sprawdzenie nie przejdzie. To bardzo częsty błąd.

Ponowienia, duplikaty i kolejność

Dostawcy się różnią, więc sprawdź dokumentację każdego z nich. Stan na wrzesień 2026:

Dokumentacja Stripe mówi też, że zdarzenia nie są gwarantowane w kolejności, w jakiej zaszły, i że to samo zdarzenie może sporadycznie przyjść więcej niż raz, dlatego zaleca śledzenie identyfikatorów zdarzeń.

Ogólna lekcja dotyczy każdego dostawcy: zdarzenia mogą przyjść późno, więcej niż raz i w złej kolejności. Twoja obsługa powinna być idempotentna — przetworzenie tego samego zdarzenia dwa razy daje ten sam efekt co raz.

Przykład: odblokowanie płatnego kursu

Sprzedajesz kurs online. Uczeń klika Kup, płaci na hostowanej przez Stripe stronie checkout i wraca na Twoją stronę.

Kruchy sposób: strona „dziękujemy” odblokowuje kurs. Jeśli uczeń zamknie przeglądarkę w trakcie przekierowania, zapłacił, ale nie ma dostępu. Jeśli ktoś odgadnie adres strony dziękczynnej, dostaje dostęp bez płacenia.

Sposób z webhookiem:

1. Gdy Stripe potwierdzi płatność, wysyła zdarzenie checkout.session.completed na /webhooks/stripe.
2. Backend weryfikuje podpis sekretem. Jeśli się nie zgadza, odpowiada 400 i nic nie robi.
3. Sprawdza, czy ten identyfikator zdarzenia był już przetworzony. Jeśli tak, odpowiada 200 i kończy.
4. Zapisuje identyfikator zdarzenia, odpowiada 200, a następnie przyznaje uczniowi dostęp i wysyła e-mail powitalny.
5. Strona „dziękujemy” tylko informuje: „Płatność otrzymana — Twój kurs pojawi się za chwilę” i sprawdza status dostępu ucznia.

Później, jeśli subskrypcja zostanie anulowana albo karta odrzucona, inne zdarzenia webhooków mówią aplikacji, by odebrać lub wstrzymać dostęp. Tak produkty subskrypcyjne pozostają zsynchronizowane z rozliczeniami — zobacz czym jest SaaS oraz jak dodać płatności do aplikacji.

Kluczowe pojęcia

• Endpoint: adres w Twojej aplikacji, który odbiera webhooki.
• Zdarzenie / payload: to, co się stało, i dane to opisujące (zwykle JSON).
• Sekret podpisu: wspólny sekret używany do weryfikacji podpisów.
• Idempotentny: bezpieczny do wykonania więcej niż raz z tym samym wynikiem.
• Polling (odpytywanie): wielokrotne pytanie API o zmiany zamiast czekania na webhook.
• Tunel: narzędzie, które daje laptopowi tymczasowy publiczny adres, by webhooki mogły do niego dotrzeć podczas developmentu.

Częste błędy i mylne przekonania

• Brak weryfikacji podpisów. Adres endpointu nie jest sekretem. Weryfikacja sprawia, że żądanie jest wiarygodne.
• Wykonywanie wolnej pracy przed odpowiedzią. Wysyłanie e-maili albo generowanie PDF-ów przed odpowiedzią może powodować przekroczenie czasu, które wyzwala ponowienia, które powodują duplikaty.
• Zakładanie dokładnie jednokrotnego dostarczenia w kolejności. Zapisuj identyfikatory zdarzeń i nie polegaj na kolejności przybycia.
• Używanie adresu podglądu. Webhooki potrzebują stabilnego, publicznego adresu. Prywatne podglądy i localhost nie są osiągalne z internetu; użyj opublikowanego adresu (albo tunelu podczas testów).
• Mieszanie sekretów testowych i produkcyjnych. Dostawcy często wydają różne sekrety podpisu dla trybu testowego i live. Przechowuj oba i używaj właściwego.
• Ślepe ufanie treści w ważnych decyzjach. Przy działaniach o wysokiej stawce rozsądnie jest po otrzymaniu zdarzenia pobrać najnowszy stan z API dostawcy.

O co poprosić swojego kreatora AI

Dodaj na serwerze endpoint POST /webhooks/stripe. Zweryfikuj podpis Stripe na surowej treści żądania, używając sekretu STRIPE_WEBHOOK_SECRET. Odrzucaj nieprawidłowe podpisy kodem 400. Zapisuj identyfikator każdego zdarzenia i pomijaj zdarzenia, które już przetworzono. Odpowiadaj szybko kodem 200, a potem obsłuż checkout.session.completed, oznaczając zamówienie jako opłacone i wysyłając paragon. Zapisuj typ zdarzenia w logu. Nie przyznawaj dostępu na stronie sukcesu checkoutu.

Następnie przetestuj: wyślij zdarzenie testowe z panelu dostawcy, wyślij to samo ponownie i wyślij żądanie z błędnym podpisem. Zmienić cokolwiek powinno tylko pierwsze.

Webhooki w Mythex

Mythex nie prowadzi osobnej usługi webhooków; prosisz agenta, by dodał endpoint webhooka w backendzie Twojej aplikacji, i wskazujesz dostawcy Twój opublikowany adres, bo webhooki potrzebują publicznego adresu. Sekret podpisu trafia do sekretów projektu, a jeśli zmienisz go w działającej aplikacji, publikujesz ją ponownie. Sekcja dokumentacji o obsłudze webhooków zawiera gotowy prompt, a szablony sklepów to dobry punkt wyjścia dla aplikacji przyjmujących płatności.

Pytania