Нотификации

Что такое нотификации

Нотификация — это HTTP POST-запрос, который MassAccess отправляет на ваш сервер при наступлении события в системе. Когда изменяется статус сообщения, обновляется номер телефона клиента или клиент взаимодействует с ботом — ваш сервер получает JSON с данными события. Никаких дополнительных API-вызовов не требуется — нотификации отправляются автоматически.

Запросы отправляются на Webhook URL, настроенный в панели управления вашей компании (Настройки → Webhook URL). Каждый запрос содержит HMAC-SHA256 подпись (заголовок X-Signature), чтобы вы могли проверить его подлинность.

Как настроить нотификации

Чтобы начать получать нотификации, войдите в панель управления компании, перейдите в раздел «Настройки» и укажите URL вашего сервера в поле «Webhook URL». После сохранения MassAccess начнёт отправлять HTTP POST-запросы на этот URL для каждого события в вашей компании.

Кнопка «Проверить» отправляет один подписанный тестовый запрос с event = webhook.test и data.test = true. Запрос содержит те же прикладные заголовки доставки, что и бизнес-события: X-Signature, Idempotency-Key и X-Webhook-Attempt. Адрес считается доступным, если сервер отвечает кодом HTTP 2xx; 4xx означает, что сервер доступен, но отверг запрос, а 5xx, тайм-аут или сетевая ошибка — что endpoint недоступен. Проверка подтверждает только приём безопасного webhook.test, но не гарантирует приём каждого типа событий. Полная проверка выполняется реальной доставкой или через /api/v1/webhooks/replay.

Типы событий

MassAccess отправляет нотификации для следующих событий:

Событие	Описание
message.status	Отправляется при переходе сообщения в терминальный статус: sent или failed. Поле data.state содержит текущий статус. Если data.state равен "failed", дополнительно включаются поля data.error_code и data.error_description.
client.phone.changed	Отправляется при изменении номера телефона клиента через эндпоинт /api/v1/change_phone. Поле data.state равно "completed" при успехе. Если изменение не удалось, data.state равен "failed" с полями error_code и error_description.
client.check	Отправляется при проверке клиента по номеру через /api/v1/client/check. data.exists указывает, есть ли у клиента активная регистрация в компании, а data.bots содержит список соответствующих ботов.
client.registered	Отправляется при регистрации нового клиента через вашего бота в месенджере и при повторном подключении клиента к боту. Полезная нагрузка включает phone, bot_name и service.
message.inbound	Текстовое сообщение подтверждённого клиента из приватного диалога Telegram или MAX. Команды, контакты, callback, status/service events и вложения исключены.