Подписки на события (webhooks)

Обзор

Позволяет управлять подписками на события, генерируемые системой. Веб-хуки — альтернатива подпискам через websocket (Token-API) для внешних систем, которые не могут держать постоянное соединение. Использовать веб-хуки не рекомендуется: каждое уведомление отправляется отдельным HTTP-запросом POST с новым соединением, синхронно и последовательно для одного адреса, без подтверждения и повторных попыток. Медленный приёмник задерживает остальные уведомления на свой адрес, а при недоступности приёмника уведомление теряется (подробнее). События модели данных (modelevents) через веб-хуки недоступны.

Формат запроса веб-хука задаётся полем ext.http_notify_format канала интеграции (подробнее): по умолчанию — POST с JSON-телом уведомления. Применяется только для запросов, авторизованных через токены каналов интеграции с типом subscr.

По результатам подписки система отправляет веб-хуки на адрес, указанный в поле url канала интеграции. Подписка требует регулярного продления с интервалом, не превышающим указанного в запросе периода регистрации подписки (поле expires).

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

В любой момент подписка может быть прекращена запросом на удаление.

В текущей версии подписка действует только для следующих классов событий:

Доступно только в рабочих доменах.

Запросы

HTTP verb Endpoint Описание

POST

/rest/v1/service/webhooks

Подписка на события

GET

/rest/v1/service/webhooks/<id>

Информация о подписке

PUT

/rest/v1/service/webhooks/<id>

Продление подписки на события

DELETE

/rest/v1/service/webhooks/<id>

Отмена подписки на события


Подписка на события

Производит подписку на события. Идентификатор подписки возвращается в ответе и может быть использован для продления и удаления подписки.

Запрос

Table 1. Поля объекта
Поле Описание

objects

Фильтр по объектам, к которым привязаны генерируемые события.

Для того, чтобы событие было отправлено по подписке, необходимо, чтобы оно было привязано хотя бы к одному из указанных объектов. Например, если указанный в фильтре пользователь является участником звонка, по которому сгенерировано событие, то событие по подписке будет отправлено. Иначе нет.

Указывается строкой "any" (без фильтра) или JSON-массивом объектов, применяемых через операцию ИЛИ. Объект задаётся строкой (например "sip1") либо в виде {"type": "sipuser", "sipuser": "sip1"}: значение берётся из поля с именем типа. Объекты для классов событий.

events

Список событий, подлежащих отправке веб-хуками.

Указывается в виде JSON-массива из строк. Каждая строка представляет маску для события в формате CLASSNAME.EVENTNAME. Если в качестве EVENTNAME указан символ *, например "callevents.*", то подписка осуществляется на все события этого класса.

expires

Период регистрации подписки, в секундах.

При отсутствии продлений по истечении интервала подписка автоматически удаляется. Максимальное значение: 86400. Большее значение уменьшается до максимального. Применённое значение возвращается в ответе в поле expires.

url

Произвольный URL для отправки веб-хуков.

Необязательный параметр. Если указан, применяется вместо url связанного канала интеграции.

Table 2. Объекты для классов событий
Класс событий Тип объекта (поле type) Значение

callevents

sipuser

Логин учетной записи SIP-пользователя

callevents

other

Номер телефона абонента

confevents

conf

Идентификатор или номер комнаты конференции

providerevents

provider

Код учетной записи провайдера телефонии

statesevents

user, sipuser

Идентификатор учетной записи пользователя, логин учетной записи SIP-пользователя

Произвольные события

sipuser

Логин учетной записи SIP-пользователя

Пример запроса
POST /rest/v1/service/webhooks HTTP/1.1
Content-Type: application/json
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

{
  "objects": [
    {
      "type":"sipuser",
      "sipuser":"sip1"
    },
    {
      "type":"sipuser",
      "sipuser":"sip2"
    }
  ],
  "events": [
    "callevents.*",
    "statesevents.sipuser_state_changed"
  ],
  "expires": 1800
}

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "subscribed",
  "expires": 1800
}
Пример неуспешного ответа
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Информация о подписке

Выводит информацию о подписке по ID.

Запрос

Пример запроса
GET /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

Ответ

Пример успешного ответа (с активной подпиской)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "objects": ["sip2", "sip1"],
  "events": ["callevents.*", "statesevents.sipuser_state_changed"],
  "url": "http://127.0.0.1",
  "expires": 296
}

Поле expires в ответе — оставшееся время действия подписки в секундах.

Пример ответа без подписок (истек срок подписки)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[]
Пример неуспешного ответа
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Продление подписки на события

Производит продление подписки на события. Допускает изменение условий предыдущей подписки.

Запрос

Поля объекта аналогичны полям запроса POST.

Пример запроса
PUT /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1
Content-Type: application/json
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

{
  "objects": [
    {
      "type":"sipuser",
      "sipuser":"sip1"
    },
    {
      "type":"sipuser",
      "sipuser":"sip2"
    }
  ],
  "events": [
    "callevents.*"
  ],
  "expires": 1800
}

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "subscribed",
  "expires": 1800
}
Пример неуспешного ответа
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Отмена подписки на события

Удаляет существующую подписку.

Запрос

Пример запроса
DELETE /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "unsubscribed"
}

См. также