Локальная отладка вебхуков: как не ловить 5xx на ровном месте

Локальная отладка вебхуков: как не ловить 5xx на ровном месте

Для локальной проверки вебхука нужен не “туннель ради туннеля”, а контролируемая точка входа. Схема простая: внешний сервис шлёт POST, ваш прокси принимает, логирует, форвардит в localhost и умеет пережить обрыв сессии. Если этого нет, вы отлаживаете не интеграцию, а магию.

ngrok удобен, когда надо быстро поднять публичный URL и посмотреть полезную нагрузку. Но у него есть типовая боль: нестабильный адрес, ручная пересборка callback URL, слабая история с повторным воспроизведением запроса. Hookdeck полезнее, если нужен буфер, ретраи и replay: можно сначала принять событие, потом прогнать его повторно, не дергая внешний API. Для вебхуков это важнее красивой консоли.

Альтернативы обычно делятся на три класса: SSH reverse tunnel, локальный reverse proxy и self-hosted intake. SSH-туннель хорош для разового дебага, но ломается на NAT, спящих ноутбуках и кривом keepalive. Собственный intake на Nginx + маленький handler надежнее: принимаете запрос, пишете raw body, ставите `X-Request-Id`, возвращаете `200 OK` только после записи в очередь. Смотрим в тело запроса, не в надежды.

Минимальный чек-лист: 1) сохраняйте raw payload до валидации; 2) проверяйте подпись до бизнес-логики; 3) делайте идемпотентный key из event_id; 4) отделяйте ack от обработки; 5) держите replay-кнопку или скрипт для повторной отправки. Идемпотентность — это не роскошь, а база.

Если локальный стенд нельзя воспроизвести одной командой, это не стенд, а музей случайностей.