Вебхуки

Вебхуки позволяют MAIA уведомлять ваш сервер о событиях звонков в реальном времени. Платформа отправляет HTTP POST-запрос на указанный вами URL с данными события и HMAC-подписью для проверки подлинности.

События

При создании эндпоинта вы выбираете, на какие события он подписан:

Событие	Когда отправляется
`call.started`	Разговор начался: на исходящем — собеседник снял трубку, на входящем — звонок принят
`call.completed`	Звонок завершён, пост-обработка готова (суммари, цель, извлечённые поля)
`call.no_answer`	Не дозвонились: трубку не сняли за таймаут дозвона либо разговор не состоялся
`call.transferred`	Агент перевёл звонок на живого оператора
`call.failed`	Звонок завершился ошибкой
`lead.created`	Текстовый канал: собран лид (достигнута цель диалога)

В call.completed также приходит поле amd: "voicemail" — трубку взял автоответчик, "bot" — на той стороне робот, null — обычный разговор. По нему интеграции могут, например, автоматически перепланировать недозвон.

Настройка

Вебхуки настраиваются per-проект в кабинете dashboard.maia-ai.com. Для каждого проекта укажите:

URL вебхука — адрес вашего HTTPS-эндпоинта, на который MAIA будет слать POST-запросы.
Секрет — строка, которой подписываются запросы (HMAC). Храните её в безопасности и используйте для проверки подписи.

Управление базой знаний и часть настроек проекта доступны только в кабинете. Вебхуки также настраиваются в кабинете per-проект, а не через публичный API.

Пример payload

Тело запроса — JSON. Состав полей может расширяться, поэтому пишите код устойчиво к дополнительным полям.

{
  "id": "delivery_uuid",
  "event": "call.completed",
  "created_at": "2026-07-02T10:00:00+00:00",
  "data": {
    "call_id": "call_uuid",
    "project_id": "project_uuid",
    "contact_id": "contact_uuid",
    "direction": "outbound",
    "phone": "+79001234567",
    "status": "completed",
    "duration_sec": 124,
    "goal_reached": true,
    "summary": "Клиент записан на четверг, 15:00",
    "extracted": { "name": "Анна", "datetime": "2026-07-03T15:00" },
    "amd": null
  }
}

id — идентификатор доставки (для дедупликации при ретраях).
data.call_id — идентификатор звонка (тот же, что и в GET /v1/public/calls/{call_id} — там же доступны транскрипт и запись).
data.goal_reached / data.summary / data.extracted — итоги пост-обработки.
data.amd — "voicemail" / "bot" / null (см. выше).

У call.started и call.transferred состав data короче: идентификаторы, направление, телефон; у перевода — transfer_to и reason.

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

Каждый запрос содержит HMAC-подпись в заголовке. Вычислите HMAC от сырого тела запроса по вашему секрету и сравните результат с подписью из заголовка. Сравнивайте подписи функцией, устойчивой к атакам по времени (constant-time).

⚠️

Проверяйте подпись по байтам сырого тела запроса, до любого парсинга или переформатирования JSON. Парсинг и обратная сериализация могут изменить байты и сломать проверку.

Псевдокод:

import hmac, hashlib
 
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Если подпись не совпадает — верните 401 и не обрабатывайте запрос.

См. также

REST API — получение деталей звонка по id.
Аутентификация — API-ключи и scopes.

MCP-сервер Кастомные инструменты