Вебхук (webhook) — это отправка запросов о событиях из onlinePBX. Запросы уведомляют сторонние сервисы об изменениях в АТС. Позволяют отслеживать звонки, их состояние и другие события onlinePBX. Информация отправляется на указанный при создании URL-адрес. Вебхуки могут использоваться для интеграции.
Для подключения вебхуков необходимо указать URL-адрес, куда будут отправляться POST-запросы. Для этого в панели управления onlinePBX перейдите в Сервисы > Интеграция, выберите «Webhooks».
Далее нажмите «+ Добавить». Появится строка с настройкой. Введите URL-адрес, а также выберите, какие именно события хотите получать. На выбор есть шесть вариантов. Нажмите «Сохранить».
Какие события можно настроить
Особенности работы вебхуков
Если сервер, на который отправляются вебхуки, десять раз подряд не отвечает, отправка вебхуков автоматически отключается.
При этом наличие от сервера ответа с ошибкой не считается отсутствием ответа: если сервер принял запрос и вернул любой ответ, счётчик неудачных попыток сбрасывается.
Что считается отсутствием ответа:
Если соединение установлено, но сервер не отвечает, система ожидает ответ до 90 секунд.
В случае получения ошибки или отсутствия ответа при передаче POST-запросов, наш сервис отправляет запрос повторно еще два раза с интервалом в пять секунд.
Количество попыток зависит от количества событий. Например, один звонок на группу из пяти пользователей может вызвать несколько вебхуков: по одному на начало, ответ и завершение звонка и по одному на дозвон до каждого пользователя.
Если в поле «URL-адрес» ввести адрес с протоколом https://, убедитесь, что на указанном адресе есть действительный сертификат безопасности (SSL-сертификат).
Для тестирования вебхуков мы добавили в меню выпадающим списком функцию «Тест».
По клику будет совершаться отправка тестового вебхука. При получении ошибки её номер или описание покажется в подсказке. В разделе «История» отобразится, что был проведен тест.
Три статуса подключения:
Сервис хранит историю отправки вебхуков и ответы от сервера. Можно посмотреть в правой части страницы.
Если произошла ошибка во время передачи, напротив поля «Тип» появится знак ошибки. При наведении на знак покажется статус, полученный от сервера, которому был отправлен вебхук.
История отображается не моментально. Обновите страницу, чтобы увидеть актуальную историю.
domain=onlinepbx.ru&event=call_start&direction=outbound&uuid=d02d3dd1-36f9-41g8-9055-3139369h6h90&caller=505&callee=120&from_domain=onlinepbx.ru&to_domain=&gateway=74991111282&date=1528886454&x-roistat-marker=google12_g_50000997109_279581000041_%D1%85%D1%80%D0%B0%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5+%D0%B2%D0%B5%D1%89%D0%B5%D0%B9+%D0%B2+%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B5&x-roistat=444308
Если в аккаунте onlinePBX зарегистрирован внешний номер от Roistat — не будет передаваться параметр x-roistat.
При использовании схемы Оператор > Roistat > Оператор > onlinePBX — не будут передаваться параметры x-roistat-marker и x-roistat.
domain=onlinepbx.ru&event=call_answered&direction=outbound&uuid=2c033c12-7310-4v4v-9b42-8bb207b17322&caller=505&callee=79111117799&to_domain=&gateway=74991111112&date=1528888621
domain=onlinepbx.ru&event=call_end&direction=outbound&uuid=6q5qq87q-0w32-4e23-8570-3r6rr6rrrr2&origin=sip&caller=145&callee=79502222919&from_domain=onlinepbx.ru&to_domain=onlinepbx.ru&gateway=74991111282&date=1528884937&call_duration=149&dialog_duration=135&hangup_cause=ORIGINATOR_CANCEL&download_url=https%3A%2F%2Fonlinepbx.ru%2Fdownload_amocrm%2FeyJ1IjoiNDAyYH1co%3D%2Frec.mp3
Время жизни ссылки на скачивание разговора — 24 часа.
domain=onlinepbx.ru&event=call_missed&direction=inbound&uuid=5329a333-ss32-4dd9-ff0f-gh84g32h5g22&caller=79221111123&from_domain=onlinepbx.ru&to_domain=onlinepbx.ru&gateway=73431111137&date=1529406933
domain=onlinepbx.ru&event=call_user_start&direction=outbound&uuid=d02d3dd1-36f9-41g8-9055-3139369h6h90&caller=505&callee=79111117960&from_domain=onlinepbx.ru&to_domain=&gateway=74991111282&date=1528886454
domain=onlinepbx.ru&event=call_transfer_answered&direction=inbound&uuid=b47fab84-5874-4de3-9c3b-8f1c744c8d8f&caller=101&callee_from=101&callee_to=102&date=1528886454
Параметры x-roistat-marker и x-roistat отправляются только при рабочей интеграции с сервисом Roistat.
№
Переменная
Пример значения переменной
Описание переменной
1
domain
pbx123.onpbx.ru
Домен, в котором состоялось событие.
2
event
call_end / call_answered / call_start / call_user_start / call_missed
Тип события. Для значений call_end и call_missed есть параметр для передачи информации из модуля «Оценка качества».
3
direction
inbound / outbound / local
Тип звонка (входящий/исходящий/внутренний).
4
uuid
5921a027-c22f-4351-b495-30a49f00e4e1
Уникальный идентификатор сессии.
5
caller
+79510057057 / 510@onlinepbx.ru
Звонящий.
6
callee
79827347182 / 102
Кому звонили.
7
from_domain
pbx123from.onpbx.ru
Домен звонящего.
8
to_domain
pbx123to.onpbx.ru
Домен того, кому звонили.
9
gateway
74922296721
Транк, на/с которого позвонили.
10
date
1527578
Дата в формате UNIX.
11
call_duration
159
Общая длительность звонка (сек.).
12
dialog_duration
145
Длительность разговора (сек.).
13
hangup_cause
NORMAL_CLEARING. Полный перечень значений в выпадающем списке после таблицы.
Причина завершения звонка.
14
x-roistat-marker
google12_g_50000997109_279581000041_%D1%85%D1%80%<...>D0%BE%D1%81%D0%BA%D0%B2%D0%B5
Маркетинговый источник визита. Отправка возможна только в запросе «Начался звонок» для входящих вызовов.
15
x-roistat
444408
Номер визита Roistat или маркер канала, если используется статический коллтрекинг. Отправка возможна только в запросе «Начался звонок» для входящих вызовов.
16
callee_from
101
Кто перевел звонок.
17
callee_to
102
На кого перевели звонок.
18
download_url
https://onlinepbx.ru/download/aFI0SVFqa<...>NRDZlSEsxSnc/rec.mp3
Ссылка на скачивание звонка. Время жизни ссылки — 24 часа.
19
origin
http_api / sip / autorecall / web_callback / callback / auto-informer / websocket_api
Тип (источник) инициализации звонка:
Список возможных причин завершения звонка (для переменной hangup_cause)
UNALLOCATED_NUMBER — Несуществующий номер.
NO_ROUTE_TRANSIT_NET — Нет транзитного маршрута.
NO_ROUTE_DESTINATION — Нет заданного маршрута.
CHANNEL_UNACCEPTABLE — Отказ не принят.
NORMAL_CLEARING — Нормальное завершение звонка.
USER_BUSY — Абонент занят.
NO_USER_RESPONSE — Абонент не ответил.
NO_ANSWER — Нет ответа.
SUBSCRIBER_ABSENT — Абонент не в сети.
CALL_REJECTED — Вызов отклонен.
NUMBER_CHANGED — Номер изменился.
REDIRECTION_TO_NEW_DESTINATION — Вызов переадресован.
EXCHANGE_ROUTING_ERROR — Ошибка оператора.
DESTINATION_OUT_OF_ORDER — Нет заданного маршрута.
INVALID_NUMBER_FORMAT — Ошибка в номере.
FACILITY_REJECTED — Услуга недоступна.
NORMAL_UNSPECIFIED — Нет канала связи.
NORMAL_CIRCUIT_CONGESTION — Нет канала связи.
NETWORK_OUT_OF_ORDER — Сеть недоступна.
NORMAL_TEMPORARY_FAILURE — Временная ошибка.
SWITCH_CONGESTION — Компьютерная сеть перегружена.
ACCESS_INFO_DISCARDED — Отказ в обслуживании.
REQUESTED_CHAN_UNAVAIL — Канал связи недоступен.
FACILITY_NOT_SUBSCRIBED — Нет доступа к услуге.
OUTGOING_CALL_BARRED — Исходящий вызов запрещен.
INCOMING_CALL_BARRED — Входящий вызов запрещен.
SERVICE_UNAVAILABLE — Сервис недоступен.
BEARERCAPABILITY_NOTIMPL — Плохое интернет-соединение.
CHAN_NOT_IMPLEMENTED — Данный тип связи не поддерживается.
FACILITY_NOT_IMPLEMENTED — Данная услуга не поддерживается.
SERVICE_NOT_IMPLEMENTED — Сервис не реализован.
INVALID_CALL_REFERENCE — Ошибка в ссылке звонка.
INCOMPATIBLE_DESTINATION — Несовместимое назначение.
INVALID_MSG_UNSPECIFIED — Ошибка сообщения.
MANDATORY_IE_MISSING — Устройство не соответствует стандартам.
MESSAGE_TYPE_NONEXIST — Тип сообщения отсутствует.
WRONG_MESSAGE — Неверное сообщение.
IE_NONEXIST — Устройство не соответствует стандартам.
INVALID_IE_CONTENTS — Устройство не соответствует стандартам.
WRONG_CALL_STATE — Устройство не соответствует стандартам.
RECOVERY_ON_TIMER_EXPIRE — Время истекло.
MANDATORY_IE_LENGTH_ERROR — Устройство не соответствует стандартам.
PROTOCOL_ERROR — Устройство не соответствует стандартам.
INTERWORKING — Неустойчивое взаимодействие.
ORIGINATOR_CANCEL — Вызов отменен.
CRASH — Критическая ошибка.
SYSTEM_SHUTDOWN — Сервер перезагружается.
LOSE_RACE — Обрыв линии связи.
MANAGER_REQUEST — Завершен через API.
BLIND_TRANSFER — Безусловный перевод.
ATTENDED_TRANSFER — Условный перевод.
ALLOTTED_TIMEOUT — Выделенный таймаут.
USER_CHALLENGE — У абонента проблемы.
MEDIA_TIMEOUT — Кончилась музыка.
PICKED_OFF — Перехвачен.
USER_NOT_REGISTERED — Абонент не зарегистрирован.
PROGRESS_TIMEOUT — Время ожидания вышло.
GATEWAY_DOWN — Внешний номер не зарегистрирован.
INVALID_GATEWAY — Не выбран внешний номер.
Все HTTP-запросы отправляются в формате POST, тело запроса в формате: application/x-www-form-urlencoded.