Локальная разработка UnifyPort webhook с ngrok

Что решает ngrok

Одна команда — и у вас публичный HTTPS URL, перенаправляющий каждый запрос на локальный порт. Всё проходящее ловит инспектор запросов на http://127.0.0.1:4040 — headers, body, тайминги, кнопка replay. Именно ради инспектора мы остаёмся на ngrok, даже когда вокруг полно бесплатных альтернатив-туннелей: то, что иначе было бы марафоном по логам, сжимается до одного взгляда.

Пятиминутный сетап обработчика UnifyPort

Допустим, обработчик слушает порт 3000:

1. 1. ngrok http 3000 — скопируйте URL https://*.ngrok-free.app, который он напечатает.
2. 2. Зарегистрируйте URL через POST /v1/webhook-endpoints — задайте url равным https://<your-tunnel>.ngrok-free.app/events и выберите нужные subscribed_events (на этапе итераций можно ["*"] для всего).
3. 3. Откройте http://127.0.0.1:4040 в браузере. Триггерните событие на стороне провайдера — Telegram DM, WhatsApp-сообщение — и наблюдайте, как оно приходит.
4. 4. Кнопкой replay отправьте ту же доставку повторно на обновлённый обработчик. Это и делает ngrok быстрее, чем каждый раз заново выманивать событие у провайдера после правки кода.

Локальная проверка подписи

Бесплатный туннель ngrok терминирует TLS на upstream, поэтому к моменту, когда обработчик видит запрос, body уже расшифрован — именно тот, что подписал UnifyPort. Это значит, что верификация подписи работает так же, как в проде: вычисляйте hex(HMAC-SHA256(secret, timestamp + "." + body)) и сверяйте с header X-Device-Signature. Если хочется убедиться вручную перед написанием кода, наш рецепт CyberChef проходит тот же алгоритм в браузере.

Когда ngrok перестаёт быть правильным ответом

• staging или demo-среды. Бесплатный URL меняется при каждом перезапуске и ломает долгоиграющие настройки. Берите платный reserved domain — или переключайтесь на Cloudflare Tunnel ради бесплатного стабильного хоста.
• Высокочастотный нагрузочный тест. На бесплатном тарифе ngrok троттлит агрессивно. Либо апгрейд, либо разворачивайте обработчик в реальной среде.
• Чисто webhook-сценарии без другого HTTP-трафика. smee.io легче — без бинарника, только клиентский скрипт.