Повтор вебхуков повторно отправляет ранее захваченный 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, чтобы захват и повтор вебхуков были встроены в ваш туннельный воркфлоу.