Локальная отладка вебхуков: не тащите прод в консоль, ловите запросы правильно

Локальная отладка вебхуков: не тащите прод в консоль, ловите запросы правильно

Когда внешний сервис шлёт POST, а у вас локальный хендлер молчит, задача не «посмотреть, пришло ли вообще». Задача — сохранить полезную нагрузку, заголовки, время доставки и ответ хендлера. Иначе вы отлаживаете тень: запрос где-то был, а что именно приехало — уже потеряно.

ngrok удобен как туннель: быстро поднимает публичный URL и прокидывает трафик на localhost. Но для нормальной диагностики одного проброса мало: логируйте сырой body, request-id, signature, retry-count. Если подпись не сходится — сначала смотрим в тело запроса, потом в базу, и только потом обвиняем внешний API. Идемпотентность — это не роскошь, а база.

Hookdeck и похожие прокси полезны, когда нужен не просто входящий туннель, а буфер между источником и вашим сервисом. Они умеют повторную доставку, просмотр событий, редрайв и фильтрацию мусора. Это спасает, когда интеграция любит 5xx на ровном месте и шлёт один и тот же event по кругу.

Альтернативы тоже рабочие: localtunnel, Cloudflare Tunnel, собственный reverse proxy с auth и allowlist. Для боевой дисциплины держите правило: один endpoint на тип события, HMAC-проверка, отдельный лог raw payload и очередь между приёмом и обработкой.

Для локальной отладки хватит простого пайплайна: туннель → приёмник → очередь → воркер. Всё остальное — косметика.