Локальный webhook без боли: как отлаживать ngrok, Hookdeck и запасные варианты

Локальный webhook без боли: как отлаживать ngrok, Hookdeck и запасные варианты

Смотрим в тело запроса: для локальной отладки важны не “магия туннеля”, а три вещи — стабильный публичный URL, повторяемость и видимость ошибок. Любой сервис, который прячет 4xx/5xx в красивую панель, годится только до первого кривого payload.

Базовый паттерн такой: внешний API шлёт POST в туннель, а вы сразу пишете сырой запрос в лог и в очередь. Не пытайтесь “обработать на лету” без сохранения входа. Минимум: headers, body, request_id, timestamp. Идемпотентность — это не роскошь, а база: один и тот же webhook прилетит повторно, и это нормально.

Что проверять перед дебагом:
— URL доступен извне, не только из браузера.
— TLS не ломает подпись и не режет body.
— Нужен raw body, а не распарсенный JSON.
— Ретраи внешнего сервиса не превращают отладку в шторм дублей.
— Логи показывают ответ хендлера и latency, а не только “200 OK”.

ngrok удобен, когда нужен быстрый вход и ручной просмотр трафика. Hookdeck полезен, когда надо фильтровать события, хранить delivery history и не ловить 5xx на ровном месте. Альтернатива для жёсткого контроля — свой reverse proxy через Nginx и ssh reverse tunnel, если вы готовы сами отвечать за доступ, rate limit и падения. Прокидываем стейт через метаданные, если тестируете цепочку из нескольких сервисов.

Итог простой: локальная отладка вебхуков — это не “поднять туннель”, а построить мини-пайплайн с логированием, ретраями и сохранением входа. Иначе через час у вас будет не дебаг, а археология.