Локальное тестирование вебхуков Stripe позволяет проверять обработчики платёжных событий на своей машине до выката в продакшен. Вы запускаете приложение локально, открываете его через публичный HTTPS-URL и получаете реальные тестовые события Stripe с полностью сохранённой проверкой подписи.
Почему вебхукам Stripe нужен публичный URL
Stripe доставляет события вебхуков через публичный интернет на настроенный URL эндпоинта. Адреса вроде 127.0.0.1:3000 недоступны с серверов Stripe, поэтому для локальной разработки нужен мост. Туннель к localhost сопоставляет публичный HTTPS-URL с вашим локальным процессом без изменений в роутере или фаерволе.
Что нужно перед тестированием
- Аккаунт Stripe в тестовом режиме.
- Локальное приложение с маршрутом вебхука (например,
/api/webhooks/stripe). - Секрет подписи вебхука Stripe, заданный в переменных окружения.
- Туннельный инструмент, сохраняющий заголовки запроса для проверки подписи.
Пошагово: локальное тестирование вебхуков Stripe с PortPreview
- Запустите приложение локально на нужном порту.
- Выполните
npx portpreview 3000, чтобы получить публичный HTTPS-URL. - В Stripe Dashboard перейдите в Developers → Webhooks и добавьте URL туннеля вместе с путём вебхука.
- Выберите события для тестирования (например,
checkout.session.completed,invoice.paid). - Запускайте тестовые события из Dashboard или CLI Stripe и изучайте каждую доставку.
- Убедитесь, что обработчик возвращает ответ 2xx и проверка подписи проходит.
PortPreview захватывает заголовки, тело и статус ответа, чтобы вы могли отлаживать неудачные доставки, не гадая по одним лишь логам сервера.
Проверка подписей вебхуков Stripe локально
Никогда не отключайте проверку подписи во время разработки. Stripe подписывает каждый payload вашим секретом вебхука, и обработчик должен валидировать заголовок Stripe-Signature точно так же, как в продакшене. Туннельные инструменты, сохраняющие исходные заголовки, позволяют тестировать реальный путь выполнения кода.
Частые ошибки подписи при локальном тестировании:
- Использование неверного секрета вебхука (секрет Dashboard вместо секрета CLI).
- Чтение уже распарсенного JSON-тела до проверки вместо сырого тела запроса.
- Расхождение часов сверх допустимого окна Stripe.
Какие события стоит тестировать локально
Checkout и подписки
Тестируйте checkout.session.completed, customer.subscription.created и invoice.payment_failed, чтобы подтвердить провижининг, выдачу доступа и логику напоминаний об оплате.
Connect и маркетплейс-сценарии
Если вы используете Stripe Connect, проверяйте события обновления аккаунта и уведомления о переводах с тестовыми подключёнными аккаунтами до запуска.
Идемпотентность и повторы
Stripe повторяет неудачные доставки. Используйте повтор вебхуков, чтобы убедиться, что обработчик безопасно обрабатывает дубли событий.
Stripe CLI против туннеля к localhost
Stripe CLI может пересылать события командой stripe listen --forward-to, что удобно для быстрых проверок. Туннель к localhost даёт стабильный публичный URL, который можно вставить в Dashboard, поделиться с коллегами и использовать с разными провайдерами — не только со Stripe. Многие команды используют оба: CLI для быстрой итерации, туннели для интеграционных тестов, повторяющих продакшен-конфигурацию.
Когда переходить с локали на staging
Локальное тестирование охватывает логику обработчика, парсинг payload и проверку подписи. Переходите на staging для специфичных для окружения проверок: управляемых секретов, миграций БД и сквозных релизных пайплайнов. Для повседневной работы над платёжными функциями локальное тестирование вебхуков Stripe сокращает итерацию с минут до секунд.
Прочитайте наше полное руководство по локальной отладке вебхуков или присоединяйтесь к листу ожидания PortPreview для webhook-first-туннельных воркфлоу.