Powtórka webhooków ponownie wysyła wcześniej przechwycony callback HTTP do twojego lokalnego handlera, bez proszenia dostawcy upstream o ponowne dostarczenie zdarzenia. Zamiast ponownie wyzwalać płatność Stripe, push GitHub czy wiadomość Twilio, odtwarzasz dokładnie to samo żądanie — nagłówki, treść i wszystko — z historii żądań.
Dlaczego powtórka webhooków ma znaczenie
Debugowanie webhooków zwykle przebiega w żmudnej pętli: wyzwól zdarzenie, sprawdź dostawę, znajdź błąd, popraw kod, wyzwól ponownie. Ponowne wyzwalanie zdarzeń upstream jest wolne, hałaśliwe i czasem niemożliwe (jednorazowe zdarzenia płatności, usunięte zasoby albo testowe API z limitem zapytań).
Powtórka skraca tę pętlę. Przechwyć raz, popraw handler, odtwarzaj ten sam payload aż przejdzie — bez dotykania zewnętrznego dostawcy.
Jak działa powtórka webhooków
- Callback trafia na adres twojego tunelu i jest przekazywany do lokalnej aplikacji.
- Narzędzie tunelujące przechwytuje całe żądanie: metodę, ścieżkę, nagłówki i treść.
- Poprawiasz kod handlera na podstawie tego, co widzisz w przechwyconym żądaniu.
- Odtwarzasz przechwycone żądanie do lokalnego endpointu jednym działaniem.
- Powtarzaj, aż handler zwróci poprawną odpowiedź.
Ten workflow wymaga tunelu do localhost z wbudowanym przechwytywaniem żądań — nie tylko przekazywaniem ruchu.
Przypadki użycia powtórki webhooków
Rozwój handlera
Buduj i testuj handlery webhooków iteracyjnie. Odtwórz to samo zdarzenie Stripe checkout.session.completed dziesięć razy, dopracowując logikę parsowania.
Testy idempotencji
Dostawcy dostarczają zduplikowane zdarzenia podczas ponowień. Odtwórz ten sam payload wielokrotnie, aby potwierdzić, że handler bezpiecznie obsługuje duplikaty — bez podwójnych obciążeń i zdublowanych rekordów.
Debugowanie weryfikacji podpisu
Gdy kontrole podpisu zawodzą, odtwórz oryginalne żądanie z nienaruszonymi nagłówkami, aby ustalić, czy problem leży w logice weryfikacji, czy w parsowaniu payloadu.
Testy regresji
Zapisuj przechwycone żądania ze zdarzeń testowych zbliżonych do produkcji i odtwarzaj je po refaktorach, aby wychwycić zmiany psujące przed deployem.
Powtórka webhooków z PortPreview
- Uruchom aplikację i wykonaj
npx portpreview 3000. - Skonfiguruj dostawcę, aby wysyłał callbacki na adres tunelu.
- Wyzwól zdarzenie testowe i sprawdź przechwycone żądanie w PortPreview.
- Popraw handler, a następnie odtwórz przechwycone żądanie.
- Zweryfikuj status i treść odpowiedzi bez ponownego wyzwalania dostawcy.
PortPreview zachowuje oryginalne nagłówki, więc weryfikacja podpisu dostawcy pozostaje miarodajna także podczas powtórki.
Powtórka a ponowne wyzwalanie: kiedy co stosować
- Powtórka: błędy logiki handlera, parsowanie payloadu, kontrole idempotencji, debugowanie podpisów.
- Ponowne wyzwalanie: testowanie generowania zdarzeń po stronie dostawcy, weryfikacja rejestracji webhooka lub integracja end-to-end z żywym stanem dostawcy.
Konfigurację dla konkretnych dostawców znajdziesz w przewodnikach o lokalnym testowaniu webhooków Stripe, lokalnym testowaniu webhooków GitHub i lokalnym testowaniu webhooków Twilio.
Dobre praktyki powtórki webhooków
- Zawsze waliduj podpisy podczas powtórki, nie tylko przy pierwszej dostawie.
- Testuj zduplikowaną dostawę, odtwarzając to samo zdarzenie wielokrotnie.
- Zachowuj historię żądań podczas gałęzi feature do kontroli regresji.
- Używaj danych uwierzytelniających trybu testowego, aby odtwarzane zdarzenia nigdy nie wpływały na dane produkcyjne.
Dołącz do listy oczekujących PortPreview, aby mieć przechwytywanie i powtórkę webhooków wbudowane w workflow tunelu.