Нотификации

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

Нотификация — это 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, X-Webhook-Id, Idempotency-Key и X-Webhook-Attempt. Адрес считается доступным, если сервер отвечает кодом HTTP 2xx; 4xx означает, что сервер доступен, но отверг запрос, а 5xx, тайм-аут или сетевая ошибка — что endpoint недоступен. Проверка подтверждает только приём безопасного webhook.test, но не гарантирует приём каждого типа событий. Полная проверка выполняется реальной доставкой или через /api/v1/webhooks/replay.

Типы событий

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

Формат нотификации

Формат входящих webhook-уведомлений о статусе сообщений. Уведомления отправляются на URL из настроек компании.

Заголовки запроса

Структура полезной нагрузки

Каждое тело нотификации — это объект JSON с общей структурой. Поля верхнего уровня присутствуют всегда; содержимое поля data зависит от типа события. Ниже приведены примеры для каждого типа события.

Изменение статуса сообщения

Отправляется, когда сообщение успешно доставлено получателю. data.state = sent.

{
  "event": "message.status",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "state": "sent"
  }
}

Изменение статуса сообщения (error)

Отправляется при ошибке доставки. data.state = failed + error_code и error_description.

{
  "event": "message.status",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "state": "failed",
    "error_code": "NETWORK_ERROR",
    "error_description": "Network error"
  }
}

Смена номера телефона

Отправляется при успешной смене номера через API /api/v1/change_phone. data.state = completed.

{
  "event": "client.phone.changed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "state": "completed"
  }
}

Смена номера телефона (ошибка)

Отправляется при ошибке смены номера. data.state = failed + error_code и error_description.

{
  "event": "client.phone.changed",
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "state": "failed",
    "error_code": "INVALID_PHONE",
    "error_description": "Invalid phone number format"
  }
}

Регистрация клиента в боте

Отправляется при регистрации нового клиента через бота (Telegram/MAX). Содержит phone, bot_name, service. Однократно.

{
  "event": "client.registered",
  "event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "phone": "12345678901",
    "bot_name": "my_telegram_bot",
    "service": "telegram"
  }
}

Проверка клиента (exists = true)

Отправляется, когда клиент с указанным номером найден в компании. data.exists = true, data.bots содержит список ботов с полями name и service.

{
  "event": "client.check",
  "event_id": "3bd290b8-09b4-48c4-920b-85b93fc3859b",
  "timestamp": "2026-07-28T21:45:31Z",
  "data": {
    "exists": true,
    "bots": [
      {
        "name": "main_max",
        "service": "max"
      }
    ]
  }
}

Проверка клиента (exists = false)

Отправляется, когда клиент с указанным номером не найден. data.exists = false, data.bots пуст.

{
  "event": "client.check",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-07-28T21:45:31Z",
  "data": {
    "exists": false,
    "bots": []
  }
}

Поля нотификации

Архитектура отправки

Ответ вашего сервера

Для подтверждения получения уведомления ваш сервер должен вернуть HTTP 200 OK. Если ответ не 200 — MassAccess будет повторять отправку.

Ваш сервер должен ответить в течение 10 секунд. Если сервер возвращает статус, отличный от 2xx, или время истекло, MassAccess повторяет доставку с экспоненциальной задержкой. После 5 неудачных попыток нотификация отбрасывается.

Проверка подписи

Заголовок X-Signature содержит HMAC-SHA256 подпись сырого тела запроса (до парсинга JSON). Чтобы проверить, что нотификация пришла от MassAccess:

1. Получите сырое тело HTTP-запроса как байты (не парсите JSON сразу)
2. Вычислите HMAC-SHA256 от сырых байтов тела, используя ваш API-ключ в качестве секрета
3. Сравните полученную HEX-строку с заголовком X-Signature. Используйте специальную функцию безопасного сравнения из стандартной библиотеки вашего языка (например: compare_digest в Python, hash_equals в PHP, timingSafeEqual в Node.js), а не обычный оператор ==. Безопасное сравнение всегда занимает одинаковое время — это не позволяет злоумышленнику подбирать подпись по времени ответа сервера. Если строки не совпали — отклоните запрос, он поддельный.

Проверяйте заголовок X-Signature (HMAC-SHA256) чтобы убедиться в подлинности уведомления:

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    """Verify webhook HMAC-SHA256 signature."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Коды ошибок нотификаций

Справочник кодов ошибок, которые могут передаваться в поле error_code webhook-нотификаций (message.status, client.phone.changed и др.). Для каждого кода указан мессенджер, в котором он может возникнуть: Telegram, MAX, оба, либо «—» для ошибок, не связанных с конкретным мессенджером.