Webhooks – Zdarzenia w czasie rzeczywistym

BigBlueButton Webhooks pozwalają Twojej aplikacji otrzymywać powiadomienia HTTP POST w czasie rzeczywistym, gdy występują zdarzenia spotkania. Zamiast wielokrotnie odpytywać getMeetings lub getMeetingInfo, rejestrujesz URL callbacku, a BigBlueButton automatycznie wysyła do Ciebie zdarzenia. Ten rozdział omawia trzy endpointy API webhooków, format callbacku, typy zdarzeń, zachowanie ponawiania oraz konfigurację serwera.

Wymagania wstępne

Pakiet bbb-webhooks musi zostać zainstalowany na serwerze BigBlueButton, zanim endpointy webhooków staną się dostępne:

sudo apt-get install bbb-webhooks

hooks/create — Zarejestruj webhook

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

Pomyślna odpowiedź

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

Duplikat rejestracji

Jeśli ten sam callbackURL zostanie zarejestrowany ponownie, odpowiedź nadal zwraca SUCCESS, ale zawiera duplicateWarning. Istniejący hook pozostaje bez zmian — meetingID, eventID i getRaw nie są aktualizowane.

<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>

Odpowiedzi błędów

hooks/list — Lista zarejestrowanych webhooków

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

Pomyślna odpowiedź

<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>

Odpowiedzi błędów

hooks/destroy — Usuń webhook

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

Pomyślna odpowiedź

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

Odpowiedzi błędów

hooks/ping — Kontrola zdrowia

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

Ten diagnostyczny endpoint nie wymaga sumy kontrolnej. Jeśli aplikacja webhooka jest osiągalna, zwraca zwykły tekst bbb-webhooks API up! (nie XML, typ treści text/plain). undocumented

Format callbacka

Callbacki webhooków są wysyłane jako żądania HTTP POST z typem treści application/x-www-form-urlencoded. Treść żądania zawiera trzy pola:

Treść przetworzonego callbacku (getRaw=false)

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

Treść surowego callbacku (getRaw=true)

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

Walidacja sumy kontrolnej callbacka

W trybie domyślnym każdy URL callbacku otrzymuje parametr zapytania checksum, który Twoja aplikacja powinna zweryfikować:

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

Formuła walidacji jest następująca:

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

Tryb Auth 2.0 / Bearer

Alternatywnie serwer można skonfigurować z auth2_0: true. W tym trybie do URL-u callbacku nie jest dołączany parametr sumy kontrolnej. Zamiast tego współdzielony sekret jest wysyłany jako token Bearer w nagłówku Authorization: undocumented

Authorization: Bearer <shared-secret>

Zachowanie callbacka

• Akceptowane kody statusu HTTP: HTTP 2xx i HTTP 401 są traktowane jako pomyślne dostarczenie. Wszystkie pozostałe kody statusu powodują ponowienie. undocumented
• Przekierowania: Odpowiedzi HTTP 3xx są śledzone (do 10 przeskoków). Callback jest uznawany za nieudany dopiero wtedy, gdy po 10 przekierowaniach nie zostanie osiągnięty 2xx/401.
• Limit czasu: Każde żądanie callbacka ma limit czasu 5 sekund (konfigurowalny przez requestTimeout).
• Interwały ponownych prób: W przypadku niepowodzenia ponowne próby używają wykładniczego opóźnienia: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 prób w ciągu około 5 minut, konfigurowalne przez retryIntervals).
• Po wyczerpaniu wszystkich ponownych prób: Hooki nietrwałe są automatycznie usuwane. Hooki trwałe kontynuują ponawianie bez końca w odstępach 60-sekundowych (konfigurowalne przez permanentIntervalReset).

Typy zdarzeń

Zdarzenia spotkania

Zdarzenia użytkownika

Zdarzenia czatu i notatek

Zdarzenia ankiety

Zdarzenia nagrywania i odtwarzania (RAP)

Konfiguracja serwera

Poniższe opcje można skonfigurować w /etc/bigbluebutton/bbb-webhooks.yml lub config/default.yml. Większość z tych opcji nie jest opisana w oficjalnej dokumentacji. undocumented

Uwagi operacyjne

• Trwałość: Hooki są przechowywane w Redis i przetrwają restarty serwera (są ponownie synchronizowane przy starcie).
• Kolejność: Callbacki są wysyłane sekwencyjnie dla każdego hooka, po jednym na raz, z zachowaniem kolejności zdarzeń.
• Unikalność URL: Wykrywanie duplikatów opiera się wyłącznie na URL-u callbacku. Tego samego URL-u nie można zarejestrować z różnymi filtrami meetingID lub eventID — pierwsza rejestracja wygrywa.
• Czyszczenie danych: Wewnętrzne mapowania spotkań są usuwane po tygodniu braku aktywności (konfigurowalne przez mappings.timeout, domyślnie: 604800000 ms).
• Zdarzenia syntetyczne: Gdy spotkanie się kończy, zdarzenia user-left są automatycznie generowane dla wszystkich nadal połączonych użytkowników, ponieważ samo BigBlueButton nie emituje UserLeftMeetingEvtMsg przy zakończeniu spotkania.
• Prywatne czaty: Tylko wiadomości z czatu publicznego generują zdarzenia chat-group-message-sent. Prywatne wiadomości są po cichu ignorowane.