Токен MAX-бота и webhook secret: как не устроить себе утечку

Почему это вообще критично

Токен MAX-бота это не просто строка “для интеграции”. Это фактический доступ к управлению ботом. В официальной документации MAX прямо сказано, что токен нельзя разглашать и что он может быть отозван при нарушении правил.

Поэтому безопасность тут начинается не с “когда-нибудь потом”, а в момент первого рабочего запроса.

Базовые правила для токена

• Не храните токен в фронтенде, Postman-коллекции для всех или в примерах на лендинге.
• Не прокидывайте токен через query-параметры: эта схема больше не поддерживается.
• Давайте доступ к токену только серверной части и строго тем сервисам, которым он нужен.
• Храните токен в env, vault или manager секретов, а не в коде.

Что делать с webhook secret

Даже если токен хранится хорошо, webhook всё равно надо защищать отдельно. Для этого у подписки есть полеsecret, которое MAX потом отправляет в заголовке X-Max-Bot-Api-Secret.

1. Сгенерируйте длинный случайный секрет.
2. Храните его так же аккуратно, как и токен.
3. Проверяйте секрет до любой бизнес-логики.

if (req.header("x-max-bot-api-secret") !== process.env.MAX_WEBHOOK_SECRET) {
  return res.status(401).json({ ok: false });
}

Если токен уже утёк

Здесь не нужно изображать спокойствие. Действуйте как при обычной утечке секрета:

1. Отзывайте токен.
2. Выпускайте новый.
3. Проверяйте, где старый токен был зашит: CI, логи, репозиторий, клиентские сборки.
4. Отдельно меняйте webhook secret, если он лежал рядом.

Если вы только собираете продовый контур, сначала имеет смысл пройти чек-лист запуска, а потом уже открывать бот для реального трафика.