Подписка на обновления

POST/subscriptions

Метод настраивает доставку событий бота через Webhook — основной механизм получения событий в продуктовых интеграциях. При активной подписке Long Polling не работает

Модель доставки событий

После вызова метода события отправляются на указанный Webhook-endpoint в виде HTTPS POST-запросов с объектом Update

Как обрабатывается событие:

При наступлении события выполняется вызов Webhook-endpoint
Выполняется TLS-валидация целевого endpoint для безопасной передачи данных
На endpoint отправляется HTTP-запрос
Если при создании подписки указан secret, проверяется заголовок X-Max-Bot-Api-Secret
При успешной валидации возвращается HTTP 200 OK
Выполняется бизнес-логика обработки события
Инициируются вызовы MAX API

Требования к Webhook-endpoint

URL и порт

Webhook-endpoint должен быть доступен по HTTPS на порту 443. Ваш сервер должен прослушивать этот порт. Порт в URL не указывается:

Код

Скопировать

https://your-domain.com/webhook

Поддерживается только порт 443. Если endpoint недоступен, события не доставляются

Безопасность соединения (TLS)

Перед отправкой событий устанавливается HTTPS-соединение и проверяется TLS-сертификат Webhook-endpoint. Это необходимо для безопасной передачи информации

Требования к сертификату:

сертификат выдан доверенным центром сертификации
самоподписанные сертификаты не поддерживаются
доменное имя в URL совпадает с CN или SAN сертификата
сервер предоставляет полную цепочку сертификатов

Если TLS-проверка не проходит, события не доставляются

Обработка запросов

Webhook-endpoint должен возвращать HTTP 200 в течение 30 секунд. Любой другой код ответа или превышение тайм-аута — ошибка доставки

Пример запроса:

BASH

Скопировать

curl -X POST "https://platform-api.max.ru/subscriptions" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://your-domain.com/webhook",
  "update_types": ["message_created", "bot_started"],
  "secret": "your_secret"
}'

Политика повторных попыток

Если доставка не удалась, выполняется до 10 повторных попыток с экспоненциально растущим интервалом:

1-я попытка: через 60 секунд
2-я попытка: через 150 секунд (60 × 2,5)
3-я попытка: через 375 секунд (150 × 2,5)
и так далее

Если в течение 8 часов по URL вебхука не получен успешный ответ, бот автоматически отписывается от вебхука

Безопасность Webhook-запросов

Параметр secret позволяет убедиться, что Webhook-запросы приходят от MAX, а не от третьей стороны. Это необязательный параметр, но мы настоятельно рекомендуем указывать его. Проверяйте значение заголовка X-Max-Bot-Api-Secret на Webhook-сервере и отклоняйте запросы при несоответствии

Если secret указан при создании подписки, он передаётся в заголовке X-Max-Bot-Api-Secret каждого Webhook-запроса

Формат и типы событий

Webhook-запрос содержит объект Update

Полный список типов событий и структура объекта описаны в разделе Update

Авторизация

access_token
apiKey

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты → Интеграция → Получить токен.

Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы

Тело запроса

url
string

URL HTTPS-endpoint вашего бота. Должен начинаться с https://

update_types
string[] optional

Пример: ["message_created", "bot_started"]

Список типов обновлений, которые хочет получать ваш бот. Для полного списка типов см. объект Update

secret
string optional
^[a-zA-Z0-9_-]{5,256}$

от 5 до 256 символов

Cекрет, который должен быть отправлен в заголовке X-Max-Bot-Api-Secret в каждом запросе Webhook. Разрешены только символы A-Z, a-z, 0-9, и дефис. Заголовок рекомендован, чтобы запрос поступал из установленного веб-узла

Результат

success
boolean

true, если запрос был успешным, false — в противном случае

message
string optional

Объяснительное сообщение, если результат не был успешным