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

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

Когда внешний сервис стучится в локалку, у вас есть только два варианта: поднимать туннель или симулировать входящий запрос. Туннель удобен для быстрой проверки, но без дисциплины превращается в генератор фантомных багов: сессия оборвалась, payload потерялся, а хендлер уже «вроде работал».

Базовый чек-лист:
— фиксируйте сырой body до парсинга;
— логируйте headers, request-id и подпись;
— отвечайте 200 сразу, а обработку уводите в очередь;
— проверяйте идемпотентность на одинаковом event_id;
— отдельно тестируйте пустой payload, битый JSON и дубликаты.

ngrok хорош, когда нужен быстрый входящий URL и минимум возни. Но он не решает ретраи, дедупликацию и нормальный контроль над трафиком. Hookdeck полезнее, если нужен буфер, повторная доставка и просмотр очереди событий без ручного шаманства. Альтернативы типа локального reverse proxy или собственного TLS-терминатора годятся, когда нужен полный контроль и воспроизводимость. Тогда вы сами решаете, что попадёт в хендлер и в каком виде.

Смотрим в тело запроса, а не в красивый логгер. Если у вас нет схемы проверки подписи, фиксации raw payload и сценария повторной доставки, локальная отладка быстро превращается в гадание по access-log. Идемпотентность — это не роскошь, а база: один и тот же вебхук должен безопасно пережить и повторный POST, и случайный ретрай.