Skonfiguruj endpoint webhooka Stripe, zweryfikuj Stripe-Signature na surowej treści żądania, testuj za pomocą stripe listen i stripe trigger oraz realizuj zamówienia z Checkout dokładnie raz.
Webhook Stripe to endpoint HTTPS na Twoim serwerze, do którego Stripe wysyła metodą POST zdarzenia w formacie JSON, na przykład checkout.session.completed po płatności. Twój handler musi zweryfikować nagłówek Stripe-Signature względem nienaruszonej surowej treści, używając sekretu whsec_ danego endpointu, szybko zwrócić 2xx i poradzić sobie z tym samym zdarzeniem dostarczonym więcej niż raz.
Najważniejsze informacje o webhookach Stripe (sprawdzone z dokumentacją Stripe, październik 2026)
Większość zepsutych integracji ze Stripe zawodzi w jednym z trzech miejsc: framework sparsował treść przed weryfikacją, handler wykonywał powolną pracę i przekroczył limit czasu albo ponowione zdarzenie zrealizowało zamówienie dwa razy. Ten przewodnik pokazuje handler, który unika wszystkich trzech problemów, a poniżej znajdziesz narzędzie weryfikujące nagłówek Stripe-Signature w Twojej przeglądarce, dzięki czemu zobaczysz dokładnie, co oblicza biblioteka.
Prawie zawsze dlatego, że treść została zmieniona przed weryfikacją, na przykład przez express.json() lub parser, który ponownie koduje JSON. Podłącz express.raw({ type: "application/json" }) tylko na trasie webhooka albo odczytaj request.text() w route handlerze Next.js. Błędny sekret daje ten sam komunikat.
checkout.session.completed dla płatności kartą oraz checkout.session.async_payment_succeeded dla metod odroczonych, takich jak polecenia zapłaty z konta. Stripe zaleca też obsługę checkout.session.async_payment_failed, aby móc poinformować klienta. Przed realizacją sprawdź payment_status sesji.
Nie. Dokumentacja Stripe mówi wprost, że klient może zapłacić i zamknąć kartę, zanim załaduje się Twoja strona sukcesu. Jeśli chcesz, używaj strony sukcesu do szybkiego potwierdzenia, ale realizację musi uruchamiać także webhook, a obie ścieżki muszą być bezpieczne przy dwukrotnym wykonaniu.
Stripe nie gwarantuje kolejności. invoice.paid może przyjść przed customer.subscription.created. Zapisuj identyfikatory zdarzeń, aby wykrywać duplikaty, i pobieraj powiązany obiekt z API, gdy potrzebujesz jego najnowszego stanu.
Kliknij Resend przy zdarzeniu w Dashboardzie (działa do 15 dni od utworzenia) albo uruchom w CLI stripe events resend <event_id> --webhook-endpoint=<endpoint_id> (do 30 dni). Automatyczne ponowienia trwają niezależnie od tego.
express.raw jest podłączony tylko na tej trasie, więc treść trafia do constructEvent jako oryginalne bajty.
request.text() zwraca niesparsowaną treść. Wyjątek w constructEvent oznacza, że podpis lub sekret jest błędny.
listen wypisuje sekret whsec_ dla tej sesji. Wpisz go do lokalnych zmiennych środowiskowych, a potem wywołuj zdarzenia w drugim terminalu.
Popularne typy zdarzeń Stripe i co z nimi zrobić
Wklej nagłówek Stripe-Signature, surową treść i swój sekret whsec_, aby zobaczyć tę samą kontrolę, którą wykonują biblioteki. Działa w Twojej przeglądarce dzięki Web Crypto i niczego nie wysyła. Używaj sekretu z trybu testowego, nigdy produkcyjnego.
Nagłówek Stripe-Signature
Surowa treść żądania
Sekret endpointu (whsec_...)
Tolerancja w sekundach
Podpisz teraz tę treść
Zweryfikuj
Wynik
Nagłówek nie zawiera znacznika czasu t=.
Nagłówek nie zawiera podpisu v1=.
Oczekiwany v1: {v}
Podpis się zgadza.
Podpis się nie zgadza: treść została zmieniona lub sekret jest błędny.
Znacznik czasu ma {n} s, mieści się w tolerancji.
Znacznik czasu ma {n} s, jest poza tolerancją: biblioteka by go odrzuciła.
Zacznij za darmo · Bez karty kredytowej