Webhooks – Події в реальному часі

Вебхуки BigBlueButton дозволяють вашому застосунку отримувати HTTP POST-сповіщення в реальному часі щоразу, коли відбуваються події зустрічі. Замість того щоб постійно опитувати getMeetings або getMeetingInfo, ви реєструєте URL-адресу зворотного виклику, і BigBlueButton автоматично надсилає вам події. У цьому розділі розглядаються три кінцеві точки API вебхуків, формат зворотного виклику, типи подій, поведінка повторних спроб і конфігурація сервера.

Передумови

Пакет bbb-webhooks має бути встановлено на сервері BigBlueButton, перш ніж стануть доступними кінцеві точки вебхуків:

sudo apt-get install bbb-webhooks

hooks/create — зареєструвати вебхук

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 — перелік зареєстрованих вебхуків

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 — видалити вебхук

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. Тіло запиту містить три поля:

Тіло обробленого зворотного виклику (getRaw=false)

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

Тіло сирого зворотного виклику (getRaw=true)

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

Перевірка контрольної суми зворотного виклику

У типовому режимі кожна 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. У цьому режимі параметр контрольної суми не додається до URL-адреси зворотного виклику. Натомість спільний секрет надсилається як токен Bearer у заголовку Authorization: undocumented

Authorization: Bearer <shared-secret>

Поведінка зворотного виклику

• Прийняті коди стану HTTP: HTTP 2xx і HTTP 401 вважаються успішною доставкою. Усі інші коди стану спричиняють повторну спробу. undocumented
• Перенаправлення: відповіді HTTP 3xx обробляються (до 10 переходів). Лише якщо після 10 перенаправлень не буде досягнуто 2xx/401, зворотний виклик вважається невдалим.
• Тайм-аут: Кожен запит зворотного виклику має тайм-аут 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 і переживають перезапуск сервера (повторно синхронізуються під час запуску).
• Порядок: Зворотні виклики надсилаються послідовно для кожного hook, по одному за раз, із збереженням порядку подій.
• Унікальність URL: Виявлення дублікатів базується виключно на URL-адресі зворотного виклику. Ту саму URL-адресу не можна зареєструвати з іншими фільтрами meetingID або eventID — перша реєстрація має пріоритет.
• Очищення даних: Внутрішні зіставлення meeting видаляються після одного тижня неактивності (налаштовується через mappings.timeout, типово: 604800000 мс).
• Синтетичні події: Коли зустріч завершується, події user-left автоматично генеруються для всіх користувачів, які все ще підключені, тому що сам BigBlueButton не генерує UserLeftMeetingEvtMsg під час завершення зустрічі.
• Приватні чати: Лише повідомлення публічного чату генерують події chat-group-message-sent. Приватні повідомлення тихо ігноруються.