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

Обзор

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

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

Через один канал интеграции может быть зарегистрировано произвольное количество подписок. Но каждое событие отправляется не более одного раза в один канал интеграции, рассматривая одну сущность канала интеграции как один отдельный экземпляр внешней системы. Достаточно лишь одной активной подписки, установившей условия на отправку события в текущий канал интеграции, подходящие для сгенерированного экземпляра события, чтобы оно было отправлено веб-хуком.

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

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

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

Запросы

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

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

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

Указывается в виде JSON-массива из объектов, применяемых через операцию ИЛИ. Каждый объект имеет поле type, и в зависимости от его значения дополнительные поля. Комбинации полей фильтра для классов событий.

events

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

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

expires

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

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

url

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

Необязательный параметр. По умолчанию применяется url, указанный в связанном канале интеграции.
Table 2. Комбинации полей фильтра для классов событий
Класс событий Тип объекта (поле type) Поля фильтра по объектам

callevents

sipuser

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

callevents

other

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

confevents

conf

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

providerevents

provider

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

registrarevents

user’s registration, sipuser’s registration

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

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"
}
Пример неуспешного ответа
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": {"sipuser": "sip2", "sipuser": "sip1"},
  "events":["callevents.*", "statesevents.sipuser_state_changed"],
  "url": "http://127.0.0.1"
}
Пример ответа без подписок (истек срок подписки)
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"
}
Пример неуспешного ответа
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"
}

См. также

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт