Локальный вебхук без боли: как отлаживать входящие события и не ловить фантомные баги

Локальный вебхук без боли: как отлаживать входящие события и не ловить фантомные баги

Первое правило — не дебажить «на глаз». Нужен туннель, который стабильно принимает входящий POST и пишет сырой запрос в лог. Подойдут ngrok, Hookdeck и аналоги, но смотреть надо не на удобство UI, а на поведение под отказами: держит ли соединение, не режет ли тело, умеет ли повторять доставку.

Смотрим в тело запроса: сохраняйте headers, raw body, query params и время прихода. Без этого вы не отличите кривой payload от проблемы на своей стороне. Для локального хендлера сразу делайте ответ 2xx только после записи события в очередь или хотя бы на диск. Идемпотентность — это не роскошь, а база: один и тот же webhook придёт повторно, и это нормальное поведение.

Полезная схема для отладки: внешний сервис → туннель → локальный прокси → валидатор → очередь → обработчик. На этапе валидатора проверяйте подпись, обязательные поля и схему JSON, а в обработчике уже занимайтесь бизнес-логикой. Если сервис любит ретраи, не отвечайте 500 просто потому, что «потом разберёмся» — получите лавину повторов и шум в логах.

Из альтернатив полезны reverse proxy на VPS, SSH reverse tunnel и временный ingress в тестовом контуре. Но у них общий минус: вы сами отвечаете за TLS, доступы и логи. Для боевой привычки лучше хранить секреты отдельно, фильтровать IP по whitelist и всегда иметь возможность воспроизвести запрос из сохранённого raw body. Ретрай-политика решает всё, а отсутствие логов — только ваши нервы.