Подписки на события (webhooks)
Обзор
Позволяет управлять подписками на события, генерируемые системой. Веб-хуки — альтернатива подпискам через websocket (Token-API) для внешних систем, которые не могут держать постоянное соединение. Использовать веб-хуки не рекомендуется: каждое уведомление отправляется отдельным HTTP-запросом POST с новым соединением, синхронно и последовательно для одного адреса, без подтверждения и повторных попыток. Медленный приёмник задерживает остальные уведомления на свой адрес, а при недоступности приёмника уведомление теряется (подробнее). События модели данных (modelevents) через веб-хуки недоступны.
Формат запроса веб-хука задаётся полем ext.http_notify_format канала интеграции (подробнее): по умолчанию — POST с JSON-телом уведомления.
Применяется только для запросов, авторизованных через токены каналов интеграции с типом subscr.
По результатам подписки система отправляет веб-хуки на адрес, указанный в поле url канала интеграции.
Подписка требует регулярного продления с интервалом, не превышающим указанного в запросе периода регистрации подписки (поле expires).
Через один канал интеграции может быть зарегистрировано произвольное количество подписок.
Если событие подходит под несколько подписок, веб-хук отправляется по каждой из них (с идентификатором подписки в поле sid).
В любой момент подписка может быть прекращена запросом на удаление.
В текущей версии подписка действует только для следующих классов событий:
-
callevents -
confevents -
providerevents -
statesevents -
Пользовательские события из сценариев
Доступно только в рабочих доменах.
Запросы
| HTTP verb | Endpoint | Описание |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Подписка на события
Производит подписку на события. Идентификатор подписки возвращается в ответе и может быть использован для продления и удаления подписки.
Запрос
| Поле | Описание |
|---|---|
|
Фильтр по объектам, к которым привязаны генерируемые события. Для того, чтобы событие было отправлено по подписке, необходимо, чтобы оно было привязано хотя бы к одному из указанных объектов. Например, если указанный в фильтре пользователь является участником звонка, по которому сгенерировано событие, то событие по подписке будет отправлено. Иначе нет. Указывается строкой |
|
Список событий, подлежащих отправке веб-хуками. Указывается в виде JSON-массива из строк.
Каждая строка представляет маску для события в формате |
|
Период регистрации подписки, в секундах. При отсутствии продлений по истечении интервала подписка автоматически удаляется.
Максимальное значение: |
|
Произвольный URL для отправки веб-хуков. Необязательный параметр. Если указан, применяется вместо |
| Класс событий | Тип объекта (поле type) | Значение |
|---|---|---|
|
|
Логин учетной записи SIP-пользователя |
|
|
Номер телефона абонента |
|
|
Идентификатор или номер комнаты конференции |
|
|
Код учетной записи провайдера телефонии |
|
|
Идентификатор учетной записи пользователя, логин учетной записи SIP-пользователя |
|
|
Логин учетной записи 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"
}
См. также
-
Компонент сценариев Генерация произвольного события.
-
Сущность канала интеграции
-
Подписка на события через websocket-подключение