Локальне тестування вебхуків 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 для тунельних воркфлоу з пріоритетом вебхуків.