Зачем мне ngrok для webhook-ов UnifyPort?

UnifyPort доставляет события на публичный HTTPS URL. Обработчик, работающий на localhost:3000, недоступен из интернета, поэтому ngrok соединяет их — одна команда публикует URL https://*.ngrok-free.app, перенаправляющий каждый запрос на ваш локальный порт.

Ломает ли ngrok верификацию HMAC-подписи?

Нет. Бесплатный туннель ngrok терминирует TLS на upstream, но байты body, которые получает ваш обработчик, — ровно те байты, что подписал UnifyPort. Верификация подписи работает идентично проду: вычисляйте hex(HMAC-SHA256(secret, timestamp + "." + body)) и сверяйте с X-Device-Signature.

Безопасно ли использовать ngrok с настоящими секретами подписи?

Для локальной разработки с секретами только для разработки — да: трафик шифруется end-to-end, а инспектор ngrok работает локально. Для staging-сред, демо или трафика production-уровня предпочтите платный reserved-домен ngrok или переключитесь на Cloudflare Tunnel, который даёт стабильное бесплатное имя хоста.

← Все инструменты

Наши заметки

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

UnifyPort доставляет события на публичный HTTPS URL. Если ваш обработчик живёт на localhost — а это так чаще всего — нужен туннель. ngrok уже много лет наш дефолт.

Открыть ngrok.com → Документация UnifyPort webhook

Что решает ngrok

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

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

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

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

Частые вопросы

Зачем мне ngrok для webhook-ов UnifyPort?: UnifyPort доставляет события на публичный HTTPS URL. Обработчик, работающий на localhost:3000, недоступен из интернета, поэтому ngrok соединяет их — одна команда публикует URL https://*.ngrok-free.app, перенаправляющий каждый запрос на ваш локальный порт.
Ломает ли ngrok верификацию HMAC-подписи?: Нет. Бесплатный туннель ngrok терминирует TLS на upstream, но байты body, которые получает ваш обработчик, — ровно те байты, что подписал UnifyPort. Верификация подписи работает идентично проду: вычисляйте hex(HMAC-SHA256(secret, timestamp + "." + body)) и сверяйте с X-Device-Signature.
Безопасно ли использовать ngrok с настоящими секретами подписи?: Для локальной разработки с секретами только для разработки — да: трафик шифруется end-to-end, а инспектор ngrok работает локально. Для staging-сред, демо или трафика production-уровня предпочтите платный reserved-домен ngrok или переключитесь на Cloudflare Tunnel, который даёт стабильное бесплатное имя хоста.