Локальный вебхук без боли: как не дебажить интеграцию вслепую

Локальный вебхук без боли: как не дебажить интеграцию вслепую

Для локальной отладки нужен не «туннель в интернет», а контролируемый вход с логами, ретраями и возможностью быстро подменить полезную нагрузку. Смотрим в тело запроса: какие заголовки прилетели, как подписан payload, где живёт secret и что будет, если хендлер ответит 500 вместо 200.

ngrok удобен как быстрый прокси до localhost, но его слабое место — хрупкая дисциплина вокруг тестовых данных. Без фильтрации и отдельного endpoint’а вы легко смешаете реальные события с мусором из ручных повторов. Держите отдельный путь, например /webhooks/test, и сразу кладите событие в очередь, а не в бизнес-логику. Идемпотентность — это не роскошь, а база.

Hookdeck полезен, когда нужен буфер, реплей и нормальная видимость по ошибкам. Он закрывает боль с повторной доставкой и даёт руками перекинуть одно и то же событие через пайплайн ещё раз. Если нужен минимализм, берите альтернативы попроще: cloudflared, localtunnel, webhook.site для инспекции входа, но помните, что без квитирования и логов это только зеркало трафика, а не отладка.

Минимальный стенд: ingress-прокси, отдельный handler, очередь, хранилище дедупликации по event_id, и журнал сырого тела запроса. Ретрай-политика решает всё: 2xx — приняли, 4xx — не наш формат, 5xx — временно не можем, пусть повторят. Прокидываем стейт через метаданные и не верим никому на слово.

Если в локальной среде нет реплея, дедупликации и видимости по ошибкам, вы не отлаживаете вебхуки — вы гадаете по 5xx на ровном месте.