Webhook

Webhook to wiadomość, którą zewnętrzna usługa sama wysyła do Twojej aplikacji, gdy coś się u niej wydarzy. Na przykład Stripe, czyli operator płatności, daje znać: „klient właśnie zapłacił”. Twoja aplikacja nie musi co chwilę dopytywać. Czeka, aż ktoś da jej znać.

Co to jest

Pomyśl o SMS-ie od kuriera: „Paczka doręczona”. Nie dzwonisz co godzinę do firmy kurierskiej z pytaniem, czy już. Wiadomość przychodzi sama, w chwili, gdy coś się wydarzyło. Webhook działa tak samo, tylko adresatem jest Twoja aplikacja, a nie Twój telefon.

W praktyce webhook to zwykły adres w Twojej aplikacji, na przykład twoja-domena.pl/api/stripe/webhook. Podajesz go usłudze: operatorowi płatności, dostawcy maili, systemowi faktur. Ona wysyła tam krótką wiadomość: „płatność udana”, „mail odbity”, „subskrypcja anulowana”. Twoja aplikacja odbiera ją i robi swoje: nadaje dostęp, zapisuje status, wysyła potwierdzenie.

Webhooki spotkasz w wielu miejscach: w płatnościach, poczcie, powiadomieniach na Discordzie czy Slacku, w automatyzacjach typu Zapier albo n8n, w GitHubie. Mechanizm jest wszędzie ten sam. Ten tekst skupia się na płatnościach, bo tam błąd kosztuje najwięcej. Polscy operatorzy (Przelewy24, PayU, Tpay) działają podobnie, choć nazywają to po swojemu, np. „notyfikacja” albo „adres powiadomień”.

Z webhookiem w parze chodzą dwie rzeczy:

• Podpis — pieczątka na wiadomości, której praktycznie nie da się podrobić bez tajnego klucza. Dlatego klucz trzymasz tylko na serwerze. Twój serwer zna wzór pieczątki (tajny klucz od usługi) i od razu odróżnia prawdziwą wiadomość od tej, którą ktoś wysłał sam.
• Idempotencja — trudne słowo na prostą rzecz: ta sama wiadomość przyjęta dwa razy daje jeden skutek. Jak przycisk piętra w windzie: naciśnięty raz czy pięć razy, winda jedzie na to samo piętro. Usługi ponawiają wysyłkę, gdy nie dostaną odpowiedzi, więc powtórki są normalne.

Co się psuje w prawdziwej aplikacji

Dostęp ze strony „dziękujemy”. Częsty skrót: po płatności klient wraca na stronę sukcesu, a aplikacja na tej podstawie daje mu produkt. Tyle że tę stronę da się otworzyć bez płacenia. To jak wydawanie paczki każdemu, kto pokaże zrzut ekranu SMS-a.

Brak sprawdzania podpisu. Adres webhooka nie jest tajemnicą. Jeśli aplikacja nie sprawdza pieczątki, każdy może wysłać „płatność udana” i dostać produkt za darmo.

Podwójny skutek. Ponowiona wiadomość nadaje dostęp drugi raz, wystawia dwie faktury albo wysyła dwa maile. Rozwiązanie: zapisuj numer każdej obsłużonej wiadomości i pomijaj te, które już znasz.

Cicha awaria. To najmniej oczywisty błąd. 8 października 2026 r. odkryliśmy u siebie, że adres zwrotny ustawiony u dostawcy maili (Mailjet) był od dawna martwy. Dostawca po serii nieudanych prób przestał tam cokolwiek wysyłać. Skutek: aplikacja nie dowiadywała się o odbitych mailach ani zgłoszeniach spamu. Nic nie świeciło na czerwono, wszystko „działało”. To jak kurier, który przestał wysyłać SMS-y, a Ty myślisz, że po prostu nie ma paczek.

Stripe webhook: jak wygląda taka wiadomość

Uproszczona, skrócona wiadomość od Stripe po udanej płatności wygląda mniej więcej tak:

{
  "id": "evt_123",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "amount_total": 9900,
      "currency": "pln",
      "customer_details": { "email": "klient@example.com" }
    }
  }
}

type mówi, co się stało, amount_total to kwota w groszach (tu 99 zł), customer_details.email to adres klienta, a id to numer wiadomości — po nim rozpoznasz powtórkę. To uproszczony fragment; prawdziwa wiadomość ma więcej pól. Do tego Stripe dokłada w nagłówku podpis.

Jak to sprawdzić u siebie

1. Wiadomość próbna. Większość usług pozwala wysłać zdarzenie testowe z panelu albo z narzędzia uruchamianego w terminalu (dla Stripe: Stripe CLI — darmowe narzędzie, które agent może obsłużyć za Ciebie). Sprawdź, że aplikacja je odbiera i zapisuje skutek.
2. Podrobiona pieczątka. Wyślij na swój adres wiadomość z błędnym podpisem. Dobra odpowiedź: odmowa (kod 400, czyli „odrzucam tę wiadomość”) i brak jakiejkolwiek zmiany w bazie.

1. Powtórka. To samo zdarzenie wysłane dwa razy ma dać jeden dostęp, jedną fakturę, jeden mail.
2. Strona sukcesu bez płatności. Otwórz adres strony „dziękujemy” bez płacenia. Dostęp nie może się pojawić.
3. Stan po stronie usługi. W panelu dostawcy znajdziesz listę adresów webhooków, ich stan i historię dostaw. Stan „dead”, „disabled” albo seria błędów oznacza, że wiadomości do Ciebie nie docierają.
4. Alarm na ciszę. Ustaw powiadomienie, które odezwie się, gdy wiadomości przestaną przychodzić.

Dokumentacja: Stripe — weryfikacja podpisu webhooka, Stripe — webhooki.

W code2saas: brama B3

Webhook to oś bramy B3 „Płatności”. Sprawdzamy dowodami, nie deklaracją: wiadomość z podrobionym podpisem dostaje odmowę, powtórka daje jeden skutek, a strona sukcesu bez płatności nie daje dostępu. Na końcu zakup kontrolny prawdziwą kartą i zwrot. Jeśli Twoja aplikacja ma przyjmować płatności, wyślij zgłoszenie do Buildera.

Najczęstsze pytania

Czy da się dostać produkt za darmo, znając tylko adres webhooka?

Tak, jeśli aplikacja nie sprawdza podpisu. Wystarczy wysłać na ten adres wiadomość „płatność udana”. Dlatego sprawdzenie podpisu to obowiązek, nie dodatek.

Co, jeśli moja aplikacja akurat nie odpowie?

Większość usług ponawia wysyłkę. Stripe w trybie na żywo próbuje przez maksymalnie 3 dni, z coraz dłuższymi przerwami, a w trybie testowym 3 razy w ciągu kilku godzin. Nieudaną wiadomość możesz też wysłać ponownie ręcznie z panelu Stripe. Inne usługi bywają mniej cierpliwe: Mailjet po serii porażek oznaczył nasz adres zwrotny jako martwy i przestał na niego wysyłać. Dlatego idempotencja i alarm na ciszę są obowiązkowe.

Czym webhook różni się od API?

Przez API to Twoja aplikacja pyta usługę: „jak tam płatność?”. Przez webhook usługa sama daje znać. Zwykle używasz obu: API do założenia płatności, webhooka do potwierdzenia, że przeszła.

Czy webhook zadziała na moim komputerze?

Nie bezpośrednio, bo usługa z internetu nie widzi Twojego komputera. Do testów służą narzędzia, które przekazują wiadomości na Twój komputer, np. Stripe CLI.