Webhooks – События в реальном времени

Webhooks BigBlueButton позволяют вашему приложению получать HTTP POST-уведомления в реальном времени при возникновении событий встречи. Вместо постоянного опроса getMeetings или getMeetingInfo вы регистрируете callback URL, и BigBlueButton автоматически отправляет вам события. В этой главе рассматриваются три эндпоинта API webhook, формат callback, типы событий, поведение повторных попыток и конфигурация сервера.

Предварительные условия

Пакет bbb-webhooks должен быть установлен на сервере BigBlueButton, прежде чем эндпоинты webhook станут доступны:

sudo apt-get install bbb-webhooks

hooks/create — зарегистрировать webhook

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/create?<parameters>&checksum=replace-with-checksum

Успешный ответ

<response>
  <returncode>SUCCESS</returncode>
    <hookID>replace-with-hook-id</hookID>
  <permanentHook>false</permanentHook>
  <rawData>false</rawData>
</response>

Дублирующая регистрация

Если тот же callbackURL регистрируется снова, ответ всё равно возвращает SUCCESS, но включает duplicateWarning. Существующий webhook остаётся без изменений — meetingID, eventID и getRaw не обновляются.

<response>
  <returncode>SUCCESS</returncode>
    <hookID>replace-with-hook-id</hookID>
  <messageKey>duplicateWarning</messageKey>
  <message>There is already a hook for this callback URL.</message>
</response>

Ответы с ошибками

hooks/list — список зарегистрированных webhook

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/list?<parameters>&checksum=replace-with-checksum

Успешный ответ

<response>
  <returncode>SUCCESS</returncode>
  <hooks>
    <hook>
    <hookID>replace-with-hook-id</hookID>
            <callbackURL><![CDATA[https://api-guide.bbbserver.com/callbacks/webhook]]></callbackURL>
    <meetingID><![CDATA[replace-with-meeting-id]]></meetingID>
      <eventID>user-joined,meeting-ended</eventID>
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
  </hooks>
</response>

Ответы с ошибками

hooks/destroy — удалить webhook

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/destroy?<parameters>&checksum=replace-with-checksum

Успешный ответ

<response>
  <returncode>SUCCESS</returncode>
  <removed>true</removed>
</response>

Ответы с ошибками

hooks/ping — проверка работоспособности

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/ping

Этот диагностический эндпоинт не требует контрольной суммы. Если приложение вебхука доступно, он возвращает строку простого текста bbb-webhooks API up! (не XML, тип содержимого text/plain). undocumented

Формат обратного вызова

Обратные вызовы вебхука отправляются как запросы HTTP POST с типом содержимого application/x-www-form-urlencoded. Тело запроса содержит три поля:

Тело обработанного callback (getRaw=false)

domain=myserver.com&event=[{"data":{"type":"event","id":"user-joined","attributes":{...},"event":{"ts":1532718316938}}}]&timestamp=1532718316953

Тело необработанного callback (getRaw=true)

domain=myserver.com&event=[{"envelope":{"name":"UserJoinedMeetingEvtMsg","routing":{"sender":"bbb-apps-akka"}},"core":{"header":{...},"body":{...}}}]&timestamp=1532718316953

Проверка контрольной суммы обратного вызова

В режиме по умолчанию каждый callback URL получает параметр строки запроса checksum, который ваше приложение должно проверить:

https://api-guide.bbbserver.com/callbacks/webhook?checksum=replace-with-checksum

Формула проверки:

sha<algo>(<callback-URL-without-checksum> + <URL-encoded-body> + <shared-secret>)

Режим Auth 2.0 / Bearer

В качестве альтернативы сервер можно настроить с помощью auth2_0: true. В этом режиме параметр checksum не добавляется к callback URL. Вместо этого общий секрет передаётся как токен Bearer в заголовке Authorization: undocumented

Authorization: Bearer <shared-secret>

Поведение обратного вызова

• Допустимые HTTP-коды статуса: HTTP 2xx и HTTP 401 считаются успешной доставкой. Все остальные коды статуса вызывают повторную попытку. undocumented
• Перенаправления: Ответы HTTP 3xx обрабатываются с переходом по перенаправлению (до 10 переходов). Только если после 10 перенаправлений не будет достигнут 2xx/401, callback считается неудачным.
• Тайм-аут: Для каждого запроса обратного вызова установлен тайм-аут 5 секунд (настраивается через requestTimeout).
• Интервалы повторных попыток: При ошибке повторные попытки используют экспоненциальную задержку: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 попыток примерно за 5 минут, настраивается через retryIntervals).
• После исчерпания всех повторных попыток: Непостоянные хуки удаляются автоматически. Постоянные хуки продолжают повторные попытки бесконечно с интервалом 60 секунд (настраивается через permanentIntervalReset).

Типы событий

События встречи

События пользователя

События чата и заметок

События опросов

События записи и воспроизведения (RAP)

Конфигурация сервера

Следующие параметры можно настроить в /etc/bigbluebutton/bbb-webhooks.yml или config/default.yml. Большинство из этих параметров не описано в официальной документации. undocumented

Примечания по эксплуатации

• Постоянство: Хуки хранятся в Redis и сохраняются после перезапуска сервера (повторно синхронизируются при запуске).
• Порядок: Обратные вызовы отправляются последовательно для каждого хука, по одному за раз, с сохранением порядка событий.
• Уникальность URL: Обнаружение дубликатов основано исключительно на callback URL. Один и тот же URL нельзя зарегистрировать с разными фильтрами meetingID или eventID — побеждает первая регистрация.
• Очистка данных: Внутренние сопоставления встреч удаляются после одной недели неактивности (настраивается через mappings.timeout, по умолчанию: 604800000 мс).
• Синтетические события: Когда встреча заканчивается, события user-left автоматически генерируются для всех ещё подключённых пользователей, потому что сам BigBlueButton не генерирует UserLeftMeetingEvtMsg при завершении встречи.
• Приватные чаты: Только сообщения публичного чата создают события chat-group-message-sent. Личные сообщения молча игнорируются.