Если Telegram WebApp не проходит проверку hash, backend не может доверять данным пользователя. В итоге mini app не авторизует клиента, не создает заказ или постоянно выдает ошибку подписи.

Проверка hash должна выполняться на сервере строго по правилам Telegram: правильный secret key, сортировка полей, исходные значения initData и сравнение подписи без самодельных упрощений.

Коротко: что сделать

  • Сохранить исходную строку initData из Telegram WebApp
  • Проверить, что hash исключен из строки проверки
  • Отсортировать пары ключ-значение по имени ключа
  • Проверить секретный ключ, полученный из bot token
  • Сравнить расчет hash на тестовом примере

Основные причины

У таких сбоев редко бывает одна универсальная причина. Надежнее идти от факта к факту: где ошибка проявляется, какие данные проходят через систему, что изменилось перед поломкой и на каком шаге цепочка перестает работать.

  • Поля initData декодируются дважды или в неправильном порядке
  • Hash включается в data_check_string
  • Используется bot token напрямую вместо HMAC-secret
  • Сортировка выполнена не по ключам
  • Проверка делается на frontend и может быть подменена

Пошаговая диагностика

Диагностику лучше проводить на одном воспроизводимом примере. Так проще увидеть не общий шум, а конкретное место, где интерфейс, сервер, интеграция или внешняя служба начинают вести себя неправильно.

  • Вывести data_check_string в лог без персональных данных
  • Сравнить расчет hash в отдельном минимальном скрипте
  • Проверить кодировку и URL decoding
  • Проверить, не меняет ли framework порядок параметров
  • Проверить время auth_date и срок жизни initData

Как исправить проблему

Исправление должно закрывать первопричину, а не только маскировать симптом. Если затронуты доступы, платежи, данные клиентов или серверные настройки, сначала сделайте резервную копию и проверьте правку на тестовом сценарии.

  • Перенести проверку hash на backend
  • Собрать data_check_string из исходных параметров без hash
  • Использовать корректный HMAC с ключом от bot token
  • Добавить проверку auth_date от старых запросов
  • Логировать причину отказа без раскрытия токена

Безопасный план решения

Не выводите bot token и полный initData в публичные логи. Для отладки используйте тестовый бот и один тестовый аккаунт, затем переносите исправленный алгоритм в production.

Чего не стоит делать

  • Не отключать проверку hash ради удобства
  • Не доверять user_id, пришедшему только с клиента
  • Не хранить bot token в frontend-коде
  • Не менять initData перед расчетом подписи

Что подготовить перед исправлением

  • Фрагмент backend-кода проверки
  • Пример initData из тестового запуска
  • Язык и framework backend
  • Понимание, где хранится bot token

FAQ

Можно ли проверять hash в браузере?

Нет. Браузер считается недоверенной средой, а секретный ключ нельзя отдавать клиенту.

Почему hash не совпадает только у части пользователей?

Часто проблема в кодировке имени, username, пробелов, спецсимволов или разных версиях клиента Telegram.

Нужно ли проверять auth_date?

Да, это защищает от повторного использования старой строки initData.

Когда стоит обратиться за помощью

Обращаться стоит, если WebApp уже принимает заказы, оплаты, заявки или персональные данные и нельзя просто выключить авторизацию.

Итог

Проверьте сбор data_check_string, HMAC-secret и серверную валидацию initData. Если нужно безопасно починить авторизацию Telegram WebApp, пишите в Telegram @rabotator_support.