Вебхуки onlinePBX

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

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

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

Подключение

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

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

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

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

Особенности работы вебхуков

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

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

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

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

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

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

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

Если в поле «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.

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