Jak naprawić błąd 500 w webhooku Stripe

1. Czy błąd 500 pochodzi ze Stripe, czy z Twojego endpointu?

Gdy Stripe pokazuje 500 Internal Server Error przy dostarczaniu webhooka, najpierw trzeba ustalić, która część integracji zwraca ten status. Zwykle żądanie dociera do skonfigurowanego adresu, ale aplikacja albo infrastruktura po drodze nie potrafi go poprawnie obsłużyć. Nie zakładałbym od razu, że problem leży po stronie Stripe. Otworzyłbym szczegóły nieudanego dostarczenia w panelu Stripe i porównał podany czas z logami aplikacji, serwera, proxy oraz bazy danych.

Ta różnica ma znaczenie praktyczne: zdarzenie może dotyczyć płatności, zwrotu lub faktury, a jego nieobsłużenie może pozostawić stan w Twojej bazie niezgodny ze stanem w Stripe. Najpierw ustal, czy odpowiedź 500 wygenerował kod aplikacji, limit czasu, serwer proxy czy inny komponent. Potem napraw przyczynę i sprawdź, czy zdarzenie można bezpiecznie przetworzyć ponownie. Nie oznaczaj płatności jako zakończonej tylko dlatego, że webhook zawiódł; stan operacji należy zweryfikować w Stripe i w danych aplikacji.

2. Jakie przyczyny wywołują błąd 500 webhooka Stripe?

Częstym źródłem problemu jest wyjątek w kodzie obsługującym zdarzenie. Może go wywołać nieoczekiwany format danych, brak powiązanego rekordu lokalnego, błąd zapisu do bazy albo założenie, że każde zdarzenie zawiera identyczne pola. Usterkę mogą powodować także niedostępna baza, błędna konfiguracja środowiska, wyczerpane zasoby lub przekroczenie limitu czasu. W logach warto szukać identyfikatora zdarzenia, trasy endpointu, czasu odpowiedzi i stosu błędu. Nie zapisuj tam sekretów, pełnych danych płatniczych ani innych informacji, które nie są potrzebne do diagnozy.

Osobno sprawdź weryfikację podpisu oraz sposób odczytu treści żądania. Stripe podpisuje webhooki, a weryfikacja zwykle wymaga oryginalnego, niezmienionego ciała żądania i sekretu przypisanego do właściwego endpointu. Jeśli framework wcześniej przekształci treść albo aplikacja użyje sekretu z innego środowiska, walidacja może się nie udać. Sama nieudana weryfikacja częściej powinna skutkować odpowiedzią klienta niż 500, ale nieprawidłowa obsługa wyjątku może zamienić ją w błąd serwera. Sprawdź również routing, TLS, konfigurację proxy, zaporę i reguły hostingu: endpoint może nie docierać do właściwej aplikacji albo pośrednik może przerwać żądanie.

3. Jak znaleźć i naprawić usterkę krok po kroku?

1. Sprawdź dostarczenie w panelu Stripe i na serwerze. Otwórz nieudane dostarczenie i zanotuj typ zdarzenia, czas, adres endpointu, kod odpowiedzi oraz identyfikator zdarzenia. Zestaw te dane z logami aplikacji i infrastruktury, uwzględniając różnice stref czasowych. Jeśli wpisu nie ma w logach aplikacji, sprawdź DNS, certyfikat TLS, routing, proxy i reguły zapory. Jeśli log pokazuje wyjątek, zanotuj jego typ i miejsce wystąpienia, lecz nie kopiuj sekretów do zgłoszeń ani publicznych narzędzi. Stripe CLI może pomóc w testowaniu obsługi zdarzeń w środowisku deweloperskim; wynik testu porównaj z konfiguracją produkcyjną, zamiast zakładać, że oba środowiska są identyczne.

2. Popraw weryfikację i obsługę żądania. Zweryfikuj podpis na podstawie oryginalnego ciała żądania i sekretu właściwego dla danego endpointu oraz środowiska. Następnie obsługuj typy zdarzeń jawnie: rozpoznane zdarzenia kieruj do odpowiedniej logiki, a nieobsługiwane zakończ kontrolowanie, bez nieoczekiwanego wyjątku. Dodaj bezpieczne logowanie błędów, by ustalić, gdzie powstaje problem, i zwracaj odpowiedź powodzenia dopiero wtedy, gdy aplikacja przyjęła zdarzenie do dalszej obsługi. Jeśli przetwarzanie wymaga długich operacji, na przykład wielu zapytań do zewnętrznej usługi, rozważ zapisanie zdarzenia do kolejki i wykonanie pracy asynchronicznie. Nie zwracaj 200 wyłącznie po to, by ukryć błąd: odpowiedź powodzenia powinna oznaczać, że aplikacja może dokończyć obsługę, także przez kolejkę.

3. Ponów zdarzenie i sprawdź skutki uboczne. Po wdrożeniu poprawki użyj funkcji ponowienia dostarczenia w panelu Stripe albo narzędzia testowego w środowisku testowym. Zanim ponowisz zdarzenie produkcyjne, upewnij się, że obsługa jest idempotentna: ponowne przetworzenie tego samego zdarzenia nie może tworzyć drugiego zamówienia, zwrotu ani wpisu księgowego. Zapisuj identyfikatory już przetworzonych zdarzeń lub stosuj równoważną ochronę na poziomie logiki biznesowej. Po ponowieniu sprawdź kod odpowiedzi, logi, stan płatności oraz powiązane rekordy w aplikacji. Jeśli błąd nadal występuje, wróć do nowych danych diagnostycznych i sprawdź kolejne żądanie, zamiast wielokrotnie ponawiać je bez ustalenia przyczyny.

4. Jak ograniczyć powtarzające się błędy webhooka?

Traktuj dostarczanie webhooków jako proces, który może być ponawiany, a nie jako gwarancję jednokrotnego wywołania. Zabezpiecz operacje przed duplikatami i zadbaj o to, by zapis identyfikatora zdarzenia oraz aktualizacja stanu nie pozostawiały danych w sprzeczności w razie przerwania pracy. Rozdziel szybkie przyjęcie żądania od dłuższego przetwarzania, stosuj rozsądne limity czasu i kontroluj dostępność bazy oraz kolejki. Monitoruj wzrost odpowiedzi 5xx, opóźnione dostarczenia i liczbę ponowień. Alarm powinien wskazywać endpoint i czas problemu, ale nie ujawniać danych płatniczych ani sekretów.

Przed wdrożeniem sprawdzaj konfigurację osobno dla środowiska testowego i produkcyjnego: adres endpointu, sekret webhooka, sposób przekazywania oryginalnego ciała żądania i dostępność trasy z internetu. Nie umieszczaj sekretu w repozytorium, komunikatach błędów ani logach; przechowuj go w bezpiecznej konfiguracji i wymień, jeśli mógł zostać ujawniony. Przygotuj obsługę nieznanych typów zdarzeń, aby zmiana po stronie integracji nie kończyła się niekontrolowanym wyjątkiem. Podczas zmian schematu bazy uwzględnij zdarzenia, które już oczekują na ponowne dostarczenie, i nie zakładaj, że każde żądanie będzie miało najnowszy kształt danych.

5. Odpowiedzi na częste pytania o błąd 500

Q1. Czy 500 oznacza, że płatność się nie powiodła?

A1. Niekoniecznie. Ten kod wskazuje, że endpoint nie obsłużył dostarczenia webhooka prawidłowo, ale sam nie rozstrzyga o stanie płatności. Sprawdź płatność w Stripe i porównaj jej stan z rekordem w swojej aplikacji. Nie zmieniaj statusu zamówienia wyłącznie na podstawie odpowiedzi webhooka.

Q2. Czy mogę ponowić dostarczenie webhooka?

A2. Tak, po usunięciu przyczyny błędu możesz ponowić dostarczenie z panelu Stripe lub użyć narzędzi testowych w odpowiednim środowisku. Najpierw potwierdź, że endpoint odpowiada prawidłowo i bezpiecznie obsługuje powtórzenia. Idempotentna logika ogranicza ryzyko podwójnego wykonania tej samej operacji. Po ponowieniu sprawdź logi, odpowiedź endpointu i stan powiązanych danych.

Q3. Jak odróżnić błąd podpisu od wyjątku aplikacji?

A3. Zacznij od kodu odpowiedzi i wpisów w logach: komunikat walidacji podpisu może wskazywać na problem z treścią żądania lub sekretem, a stos błędu może ujawnić wyjątek aplikacji. Sprawdź, czy sekret należy do właściwego endpointu i środowiska, oraz czy framework udostępnia oryginalne ciało żądania do weryfikacji. Nie zapisuj sekretu ani pełnych danych podpisu w logach. Jeśli logowanie nie wskazuje źródła błędu, dodaj bezpieczne logi diagnostyczne i porównaj je z danymi konkretnego dostarczenia w Stripe.