Вебхуки onlinePBX

Обновлено 22 сентября 2026 г. · ≈ 9 мин чтения

Скачать: PDF Word HTML
Содержание 13

Вебхук (webhook) — это отправка запросов о событиях из onlinePBX. Запросы уведомляют сторонние сервисы об изменениях в АТС. Позволяют отслеживать звонки, их состояние и другие события onlinePBX. Информация отправляется на указанный при создании URL-адрес. Вебхуки могут использоваться для интеграции.

Подключение

Для подключения вебхуков необходимо указать URL-адрес, куда будут отправляться POST-запросы. Для этого в панели управления onlinePBX перейдите в Сервисы > Интеграция, выберите «Webhooks».

Далее нажмите «+ Добавить». Появится строка с настройкой. Введите URL-адрес, а также выберите, какие именно события хотите получать. На выбор есть шесть вариантов. Нажмите «Сохранить».

Какие события можно настроить

  • Начало звонка (call_start). Событие отправляется сразу после начала звонка.
  • Дозвон до пользователя (call_user_start). Событие отправляется при дозвоне до внутреннего пользователя onlinePBX.
  • Ответили (call_answered). Событие отправляется при ответе на звонок.
  • Завершили (call_end). Событие отправляется при завершении звонка.
  • Пропущенный (call_missed). Событие отправляется по пропущенному вызову.
  • Перевод звонка (call_transfer_answered). Событие отправляется в момент перевода звонка.

Особенности, автоматическое отключение и восстановление работы вебхуков

1. Количество вебхуков зависит от количества событий. Например, один звонок на группу из пяти пользователей может вызвать несколько вебхуков: по одному на начало, ответ и завершение звонка и по одному на дозвон до каждого пользователя.

2. Если сервер, на который отправляются вебхуки, десять раз подряд не отвечает, и с первой неуспешной попытки прошло не менее десяти минут, отправка вебхуков автоматически отключается.

При этом наличие ответа с ошибкой от сервера не считается отсутствием ответа: если сервер принял запрос и вернул любой ответ, счётчик неудачных попыток сбрасывается. Если в течение часа не было новых запросов или запросов без ответа, накопленный счётчик также сбрасывается.

Что считается отсутствием ответа:

  • сервер не отвечает на запрос;
  • соединение отклонено;
  • домен не определяется;
  • соединение сразу разорвано;
  • произошла другая сетевая ошибка.

Если соединение установлено, но сервер не отвечает, система ожидает ответ до 90 секунд.

3. В случае получения ошибки или отсутствия ответа при передаче POST-запросов наш сервис отправляет запрос повторно ещё два раза с интервалом в пять секунд.

4. При автоматическом отключении вебхуков напротив адреса снимаются все галки событий, а сам URL-адрес остаётся в списке. Индикатор статуса показывает только результат последней отправки. Примерно через минуту события на этот адрес перестают уходить, другие вебхуки аккаунта работают как обычно.

5. Через 30 минут после отключения из onlinePBX отправляется тестовый вебхук. В случае отсутствия ответа — через 24 часа после первой проверки отправляется второй тестовый вебхук. Ещё через 24 часа после второй проверки отправляется третий вебхук. Эти проверки не отображаются в истории вебхуков, их видно только на сервере адреса. Если от сервера поступит ответ (даже с кодом ошибки) — отправка вебхуков на адрес автоматически включается по тем же событиям, что были ранее настроены.

6. Если внести вручную изменения в работу вебхуков, например, изменить события или адрес, тестовые вебхуки для проверки перестанут отправляться.

7. На каждую неуспешную проверку с тестовым вебхуком формируются уведомления об отключении вебхуков, если подключён тип уведомлений «Сбои». Если при второй или третьей проверке адрес возобновил работу, приходит уведомление о возобновлении работы вебхуков. Подробнее о настройке уведомлений в статье.

Если в поле «URL-адрес» ввести адрес с протоколом https://, убедитесь, что на указанном адресе есть действительный сертификат безопасности (SSL-сертификат).

Статус

Для тестирования вебхуков мы добавили в меню выпадающим списком функцию «Тест».

По клику будет совершаться отправка тестового вебхука. При получении ошибки её номер или описание покажется в подсказке. В разделе «История» отобразится, что был проведен тест.

Три статуса подключения:

  1. Серый «Не подключен» — показывается до отправки первого события.
  2. Зелёный «Подключен» — после успешного прохождения теста.
  3. Красный «Отключен» — при получении ошибки в ходе теста.

История

Сервис хранит историю отправки вебхуков и ответы от сервера. Можно посмотреть в правой части страницы.

Если произошла ошибка во время передачи, напротив поля «Тип» появится знак ошибки. При наведении на знак покажется статус, полученный от сервера, которому был отправлен вебхук.

История отображается не моментально. Обновите страницу, чтобы увидеть актуальную историю.


Примеры запросов

Начался звонок

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 Тип (источник) инициализации звонка:
• http_api — звонок инициализирован через нашу API.
• sip — звонок инициализирован устройством (обычный звонок от пользователя).
• autorecall — звонок инициализирован приложением автоперезвона.
• web_callback / 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.

Была ли статья полезной?