Повтор вебхуків повторно надсилає раніше захоплений HTTP-колбек вашому локальному обробнику, не просячи upstream-провайдера знову доставити подію. Замість повторного запуску платежу Stripe, push GitHub чи повідомлення Twilio ви відтворюєте точний запит — заголовки, тіло й усе інше — з історії запитів.
Чому повтор вебхуків важливий
Налагодження вебхуків зазвичай іде втомливим циклом: запустити подію, перевірити доставку, знайти баг, виправити код, запустити знову. Повторний запуск upstream-подій повільний, галасливий і часом неможливий (одноразові платіжні події, видалені ресурси чи тестові API з лімітом запитів).
Повтор стискає цей цикл. Захопіть один раз, виправте обробник, відтворюйте той самий payload, доки він не пройде — не торкаючись зовнішнього провайдера.
Як працює повтор вебхуків
- Колбек надходить на URL вашого тунелю й пересилається локальному застосунку.
- Тунельний інструмент захоплює повний запит: метод, шлях, заголовки й тіло.
- Ви виправляєте код обробника на основі того, що бачите в захопленому запиті.
- Ви відтворюєте захоплений запит до локального ендпоінта одним дієм.
- Повторюйте, доки обробник не поверне правильну відповідь.
Цей воркфлоу потребує тунелю до localhost із вбудованим захопленням запитів — не просто пересилання трафіку.
Сценарії використання повтору вебхуків
Розробка обробника
Створюйте й тестуйте обробники вебхуків ітеративно. Відтворіть ту саму подію Stripe checkout.session.completed десять разів, удосконалюючи логіку парсингу.
Тестування ідемпотентності
Провайдери доставляють дубльовані події під час повторів. Відтворіть той самий payload кілька разів, щоб підтвердити, що обробник безпечно опрацьовує дублі — без подвійних списань і дубльованих записів.
Налагодження перевірки підпису
Коли перевірка підпису падає, відтворіть оригінальний запит з незмінними заголовками, щоб локалізувати, де проблема — у логіці перевірки чи в парсингу payload.
Регресійне тестування
Зберігайте захоплені запити з наближених до продакшену тестових подій і відтворюйте їх після рефакторингів, щоб виявити ламкі зміни до деплою.
Повтор вебхуків з PortPreview
- Запустіть застосунок і виконайте
npx portpreview 3000. - Налаштуйте провайдера надсилати колбеки на URL тунелю.
- Запустіть тестову подію й перевірте захоплений запит у PortPreview.
- Виправте обробник, потім відтворіть захоплений запит.
- Перевірте статус і тіло відповіді, не запускаючи провайдера повторно.
PortPreview зберігає оригінальні заголовки, тож перевірка підпису провайдера лишається значущою й під час повтору.
Повтор проти повторного запуску: коли що використовувати
- Повтор: баги логіки обробника, парсинг payload, перевірки ідемпотентності, налагодження підписів.
- Повторний запуск: тестування генерації подій на боці провайдера, перевірка реєстрації вебхука або наскрізна інтеграція з живим станом провайдера.
Налаштування під конкретних провайдерів дивіться в посібниках із локального тестування вебхуків Stripe, локального тестування вебхуків GitHub і локального тестування вебхуків Twilio.
Найкращі практики повтору вебхуків
- Завжди валідуйте підписи під час повтору, а не лише при першій доставці.
- Тестуйте дубльовану доставку, відтворюючи ту саму подію кілька разів.
- Зберігайте історію запитів на feature-гілках для регресійних перевірок.
- Використовуйте облікові дані тестового режиму, щоб відтворені події ніколи не впливали на продакшен-дані.
Приєднайтеся до списку очікування PortPreview, щоб захоплення й повтор вебхуків були вбудовані у ваш тунельний воркфлоу.