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

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

Для локальной отладки нужен не «туннель ради туннеля», а воспроизводимый контур. Базовая схема простая: внешний сервис шлёт POST на публичный URL, прокси принимает payload, пишет сырой запрос в лог и форвардит его на localhost. Смотрим в тело запроса, а не в «пример из документации» — именно там всплывают битые подписи, пустые поля и неожиданные content-type.

ngrok удобен как быстрый временный хендлер: поднял, получил URL, пробросил на <code>127.0.0.1:3000</code>, поймал запрос. Но для диагностики он слаб как стеклянный мост: TTL URL, ручной ретрай, минимум контроля над очередью и повторами. Если нужно не просто увидеть payload, а повторить его, заморозить, переиграть и сравнить заголовки — Hookdeck и похожие прокси полезнее. Они дают буферизацию, replay, фильтрацию событий и нормальный аудит. Идемпотентность — это не роскошь, а база.

Минимальный локальный приемник должен делать три вещи:
• принимать сырой body без «умных» преобразований
• проверять HMAC/секрет до бизнес-логики
• отвечать 2xx только после записи в очередь или хотя бы на диск
Иначе вы получаете красивый лог и потерянный webhook, а потом долго гадаете, кто съел событие. Ретрай-политика решает всё: если ваш endpoint падает, внешний сервис будет стучаться снова, и повторный запрос обязан проходить без дубляжа.

Практика для отладки: отдельно логируйте headers, raw body, время приема и результат валидации; сохраняйте пример payload в файл; поднимайте локальный consumer, который умеет переиграть запрос из файла через <code>curl</code>. Для сложных пайплайнов держите replay-стенд с очередью, чтобы прокидывать стейт через метаданные и не зависеть от ручных кликов.

Выбирайте инструмент по задаче: быстрый просмотр — ngrok, полноценная трассировка и replay — Hookdeck, полный контроль — свой reverse proxy с логированием и очередью. Если не сохраняете сырой запрос, вы отлаживаете не вебхук, а его тень.

—
Рядом по жанру: @wp_automation_hacks_ww