Telegram Webhook secret_token и HMAC: что проверять на стороне получателя
secret_token в Telegram Bot API — не HMAC-подпись. После настройки через setWebhook Telegram передаёт то же значение в заголовке X-Telegram-Bot-Api-Secret-Token. Получатель сравнивает его с настроенным токеном. В UnifyPort действует другой контракт: если подпись включена, нужно вычислить HMAC-SHA256 от временной метки и исходных байтов тела запроса, затем проверить X-Device-Signature. Эти проверки не взаимозаменяемы.
Главное различие
- Заголовок Telegram содержит сам общий секрет, а не дайджест JSON-тела.
- Подпись UnifyPort связывает исходное тело и
X-Device-Timestampсsigning_secretконкретного endpoint. - Оба варианта требуют HTTPS, защиты секретов и идемпотентной обработки.
- Способ проверки выбирают по доверенной конфигурации маршрута, а не по непроверенному полю
providerили наличию произвольного заголовка.
Здесь речь об аутентификации запросов, а не о выборе типа аккаунта. Если вы ещё выбираете между ботом и существующим аккаунтом для переписки, начните со сравнения Telegram Bot API webhook и единого входящего webhook.
Что именно проверяет Telegram secret_token
В официальной документации Telegram Bot API secret_token описан как необязательный параметр setWebhook. Допустимая длина — 1–256 символов; разрешены A-Z, a-z, 0-9, _ и -. После настройки Telegram передаёт это значение в X-Telegram-Bot-Api-Secret-Token с каждым webhook-запросом.
Если получатель требует такую защиту, запрос без заголовка или с несовпадающим значением не должен попадать в доверенную очередь обработки. Совпадение подтверждает владение настроенным значением, но не создаёт отдельной криптографической связи между токеном и телом запроса.
Это особенно важно при использовании прокси или сервиса пересылки. Компонент, который видит токен, способен отправить тот же токен с другим телом. HTTPS защищает соединение, но статический заголовок сам по себе не обнаруживает изменение тела после завершения TLS-соединения на промежуточном узле. Это различие границ доверия, а не причина отказываться от официального Bot API.
Рекомендуется выделить отдельный секрет для webhook: не использовать вместо него токен бота и не вставлять его в публичные сервисы сбора запросов. Скрывайте значение в журналах доступа, выгрузках трассировок и скриншотах для поддержки.
Статический заголовок и подпись тела
HMAC — механизм аутентификации сообщений с общим секретным ключом. В документированном контракте UnifyPort получатель заново вычисляет дайджест заданных данных, а не сравнивает заголовок подписи с секретом напрямую.
| Вопрос | Telegram Bot API webhook | Подписанный webhook UnifyPort |
|---|---|---|
| Настройка | setWebhook.secret_token | signing_secret endpoint |
| Проверяемый заголовок | X-Telegram-Bot-Api-Secret-Token | X-Device-Signature |
| Передаваемое значение | Сам настроенный токен | HMAC-SHA256 в шестнадцатеричном виде |
| Включено ли тело в проверку? | Нет | Да, исходные байты |
| Включена ли временная метка? | Нет | Да, X-Device-Timestamp |
| Действие получателя | Сравнить заголовок с токеном | Вычислить и сравнить дайджест |
| Гарантирует однократную обработку? | Нет | Нет |
В UnifyPort подписывается строго следующая последовательность:
<X-Device-Timestamp>.<raw request body>Временная метка имеет формат RFC 3339 UTC, разделитель — буквальная точка. Форматирование JSON, изменение пробелов или повторная сериализация после разбора могут изменить подписанные байты. signing_secret служит ключом HMAC, а не ожидаемым значением заголовка подписи.
При пустом signing_secret подпись UnifyPort отключена и X-Device-Signature не передаётся. Если получатель требует подписанные запросы, он должен отклонить такой запрос, а не незаметно переключаться на другой способ аутентификации.
Разделите входящие маршруты
Практичный вариант — отдельные маршруты приложения для нативных обновлений Telegram и событий UnifyPort. Это рекомендация по архитектуре приложения, а не новый endpoint провайдера.
- Закрепите отправителя и секрет за маршрутом. Ожидаемый механизм должен быть определён в конфигурации до приёма трафика.
- Проверяйте подлинность до передачи в обработку. Для Telegram проверяйте заголовок с токеном; для подписанного UnifyPort — HMAC исходного тела и допустимость временной метки.
- Проверяйте правильную структуру данных. Нативный Telegram
Updateнельзя передавать обработчику, ожидающему конверт UnifyPortmessage.received. - Надёжно сохраняйте принятую работу. Аутентификация, идемпотентность и проверка бизнес-полномочий должны оставаться отдельными этапами.
- Записывайте причину отказа, а не секрет. В журнале достаточно указать, какая проверка не прошла.
Не используйте на общем маршруте правило «подходит любой из двух заголовков». Более слабая или случайно включённая ветка станет альтернативой запланированной политике проверки. В частности, токен Telegram не должен заменять обязательную HMAC-подпись на маршруте UnifyPort.
Подробности второго контракта разобраны в руководстве по защите HMAC от повторного воспроизведения и обработке повторных доставок. Время внутри JSON-сообщения не заменяет временную метку, защищённую подписью доставки.
Приёмочные проверки перед запуском
Ниже предложены тесты, а не результаты уже выполненного тестирования. Проводите их в изолированной среде с секретами под вашим контролем.
| Проверка | Ожидаемое поведение получателя |
|---|---|
| Заголовок Telegram отсутствует или неверен | Отклонить до доверенной обработки |
| Токен Telegram верен, тело изменено | Один заголовок не выявит изменение; нужны проверка данных и доверенная транспортная граница |
| Тело UnifyPort изменено после подписания | Отклонить из-за несовпадения дайджеста |
| Подпись UnifyPort верна, но время вне допустимого окна | Отклонить согласно политике свежести |
| Токен Telegram отправлен на маршрут UnifyPort | Отклонить, не менять механизм проверки |
| Подлинное обычное событие доставлено повторно | Принять идемпотентно, не повторяя бизнес-действие |
Выбирайте допустимое временное окно с учётом точности часов и условий доставки, а не копируйте значение другого сервиса. Успешная аутентификация также не даёт права автоматически выполнять любую команду, содержащуюся в сообщении.
Где полезен UnifyPort и каковы ограничения
Неофициальный интерфейс UnifyPort предоставляет нормализованные события подключённых аккаунтов для переписки. HMAC защищает участок от UnifyPort до вашего получателя. Это не нативная подпись Telegram и не сквозное доказательство авторства пользователя Telegram.
Если продукт уже работает как Telegram-бот, реализуйте документированную защиту Telegram на его входе. Менять платформу только ради другого механизма аутентификации не требуется. Если UnifyPort используется для очереди существующего аккаунта или нескольких каналов, следуйте его контракту и включайте подпись при создании webhook endpoint.
Частые вопросы
Нужно ли вычислять HMAC с Telegram secret_token?
Не для проверки документированного секретного заголовка Bot API. Сравните заголовок с настроенным токеном. Не придумывайте алгоритм подписи тела для заголовка, который передаёт сам токен.
Можно ли напрямую сравнить X-Device-Signature и signing_secret?
Нет. Вычислите HMAC-SHA256 от временной метки и исходного тела по правилам документации, затем сравните дайджест с полученной шестнадцатеричной подписью.
Предотвращает ли один из механизмов повторную обработку?
Нет. Аутентификация и устранение дублей — разные задачи. Сохраняйте принятую работу и делайте последующие действия идемпотентными. HMAC сам по себе не обеспечивает однократную доставку.
Следующий шаг и источники
Используйте справочник доставки webhook и проверки подписи как контракт реализации получателя UnifyPort.
Источники проверены 2026-09-17:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.