Lokalne testowanie webhooków Stripe pozwala zweryfikować obsługę zdarzeń płatności na własnej maszynie przed wdrożeniem na produkcję. Uruchamiasz aplikację lokalnie, udostępniasz ją przez publiczny adres HTTPS i odbierasz prawdziwe zdarzenia Stripe w trybie testowym z w pełni zachowaną weryfikacją podpisu.
Dlaczego webhooki Stripe potrzebują publicznego URL
Stripe dostarcza zdarzenia webhooków przez publiczny internet na skonfigurowany adres endpointu. Adresy takie jak 127.0.0.1:3000 są nieosiągalne z serwerów Stripe, więc rozwój lokalny wymaga mostu. Tunel do localhost mapuje publiczny adres HTTPS na twój lokalny proces bez zmian w routerze czy firewallu.
Czego potrzebujesz przed testowaniem
- Konta Stripe w trybie testowym.
- Lokalnej aplikacji z trasą webhooka (na przykład
/api/webhooks/stripe). - Sekretu podpisu webhooka Stripe ustawionego w zmiennych środowiskowych.
- Narzędzia tunelującego, które zachowuje nagłówki żądania do weryfikacji podpisu.
Krok po kroku: lokalne testowanie webhooków Stripe z PortPreview
- Uruchom aplikację lokalnie na docelowym porcie.
- Wykonaj
npx portpreview 3000, aby wygenerować publiczny adres HTTPS. - W panelu Stripe przejdź do Developers → Webhooks i dodaj adres tunelu oraz ścieżkę webhooka.
- Wybierz zdarzenia, które chcesz testować (na przykład
checkout.session.completed,invoice.paid). - Wyzwalaj zdarzenia testowe z panelu lub CLI Stripe i sprawdzaj każdą dostawę.
- Upewnij się, że handler zwraca odpowiedź 2xx i że walidacja podpisu przechodzi.
PortPreview przechwytuje nagłówki, treść i status odpowiedzi, więc możesz debugować nieudane dostawy bez zgadywania wyłącznie na podstawie logów serwera.
Walidacja podpisów webhooków Stripe lokalnie
Nigdy nie wyłączaj weryfikacji podpisu podczas developmentu. Stripe podpisuje każdy payload twoim sekretem webhooka, a handler powinien walidować nagłówek Stripe-Signature dokładnie tak jak na produkcji. Narzędzia tunelujące, które zachowują oryginalne nagłówki, pozwalają przetestować prawdziwą ścieżkę kodu.
Typowe błędy podpisu podczas testów lokalnych:
- Użycie złego sekretu webhooka (sekret z panelu vs. sekret z CLI).
- Odczyt sparsowanego ciała JSON przed weryfikacją zamiast surowego ciała żądania.
- Przesunięcie zegara przekraczające okno tolerancji Stripe.
Zdarzenia warte testowania lokalnie
Checkout i subskrypcje
Testuj checkout.session.completed, customer.subscription.created i invoice.payment_failed, aby potwierdzić provisioning, nadawanie dostępu i logikę ponagleń.
Przepływy Connect i marketplace
Jeśli używasz Stripe Connect, zwaliduj zdarzenia aktualizacji konta i powiadomienia o transferach na testowych kontach połączonych przed startem.
Idempotencja i ponowienia
Stripe ponawia nieudane dostawy. Użyj powtórki webhooków, aby potwierdzić, że handler bezpiecznie obsługuje zduplikowane zdarzenia.
Stripe CLI a tunel do localhost
Stripe CLI potrafi przekazywać zdarzenia poleceniem stripe listen --forward-to, co sprawdza się przy szybkich testach. Tunel do localhost daje stabilny publiczny adres, który wkleisz do panelu, udostępnisz zespołowi i wykorzystasz u wielu dostawców — nie tylko w Stripe. Wiele zespołów używa obu: CLI do szybkiej iteracji, tuneli do testów integracyjnych odzwierciedlających konfigurację produkcyjną.
Kiedy przejść z lokalnego na staging
Testy lokalne pokrywają logikę handlera, parsowanie payloadu i walidację podpisu. Przejdź na staging dla kontroli zależnych od środowiska: zarządzanych sekretów, migracji bazy i pełnych pipeline'ów release. W codziennej pracy nad funkcjami płatności lokalne testowanie webhooków Stripe skraca iterację z minut do sekund.
Przeczytaj nasz pełny przewodnik o lokalnym debugowaniu webhooków lub dołącz do listy oczekujących PortPreview, aby korzystać z workflow tuneli zorientowanych na webhooki.