Webhooki

Jest to aplikacja node.js, która nasłuchuje wszystkich zdarzeń na BigBlueButton i wysyła żądania POST ze szczegółami dotyczącymi tych zdarzeń do hooków zarejestrowanych poprzez API. Hakiem jest dowolny zewnętrzny adres URL, który może odbierać żądania HTTP POST.

Te elementy web hook pozwalają aplikacjom innych firm subskrybować różne zdarzenia, które mają miejsce podczas sesji BigBlueButton. Zdarzeniem może być: utworzono spotkanie, dołączył użytkownik, przesłano nową prezentację , użytkownik opuścił, trwa przetwarzanie nagrania i wiele innych. Całą listę zdarzeń generujących wywołania web hooków możesz zobaczyć w tym pliku.

Instalacja

Aby zainstalować webhooki, uruchom następującą komendę na serwerze BigBlueButton:

$ sudo apt-get install bbb-webhooks

Rejestrowanie hooków: wywołania API

Ta aplikacja dodaje trzy nowe wywołania API do API BigBlueButton.

Haki/Utwórz

Tworzy nowy hak. To połączenie jest idempotentne: możesz je wywołać wielokrotnie z tymi samymi parametrami bez skutków ubocznych (podobnie jak wezwanie na spotkania create). Opcjonalnie może otrzymać parametr meetingID: jeśli zostanie poinformowany, ten hak będzie otrzymywać tylko zdarzenia dla tego spotkania; w przeciwnym razie hak będzie globalny i będzie otrzymywać zdarzenia dla wszystkich spotkań na serwerze.

Hak można zarejestrować w dowolnym momencie. Nawet hooki dla konkretnych meetingID można zarejestrować nawet jeśli nie ma jeszcze spotkania z tym ID. Po utworzeniu spotkania hak otrzyma zdarzenia .

Hooki są trwale przechowywane na Redis i będą włączone, dopóki hook nie zostanie jawnie usunięty przez API.

URL zasobu: http://yourserver.com/bigbluebutton/api/hooks/create?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Reakcja w przypadku pomyślnej rejestracji haka:

<response>
  <returncode>SUCCESS</returncode>
  <hookID>12345678-1234-5678-1234-567812345678</hookID>
  <permanentHook>false</permanentHook>
  <rawData>false</rawData>
</response>

Reakcja, gdy hak jest już zarejestrowany:

<response>
  <returncode>SUCCESS</returncode>
  <hookID>12345678-1234-5678-1234-567812345678</hookID>
  <messageKey>duplicateWarning</messageKey>
  <message>There is already a hook for this callback URL.</message>
</response>

Reakcja w przypadku błędu rejestracji hooka:

<response>
  <returncode>FAILED</returncode>
  <messageKey>createHookError</messageKey>
  <message>An error happened while creating your hook. Check the logs.</message>
</response>

Haki/Zniszcz

Usuń wcześniej utworzony hak. W parametrach należy przekazać hookID, aby zidentyfikować hak, który ma zostać usunięty.

URL zasobu: http://yourserver.com/bigbluebutton/api/hooks/destroy?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Reakcja po pomyślnym usunięciu haka:

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

Reakcja w przypadku nie znalezienia haka:

<response>
  <returncode>FAILED</returncode>
  <messageKey>destroyMissingHook</messageKey>
  <message>The hook informed was not found.</message>
</response>

Reakcja w przypadku braku przekazania haka w parametrach:

<response>
  <returncode>FAILED</returncode>
  <messageKey>missingParamHookID</messageKey>
  <message>You must specify a hookID in the parameters.</message>
</response>

Reakcja w przypadku błędu przy usuwaniu haka:

<response>
  <returncode>FAILED</returncode>
  <messageKey>destroyHookError</messageKey>
  <message>An error happened while removing your hook. Check the logs.</message>
</response>

Hooki/Lista

Zwraca zarejestrowane hooki. Jeśli meetingID zostanie poinformowany, zwróci hooki utworzone specjalnie dla tego spotkania oraz wszystkie globalne hooki (ponieważ otrzymują także zdarzenia dla to meetingID). Jeśli nie zostanie poinformowany żaden meetingID, zwraca wszystkie dostępne hooki (a nie tylko globalne hooki, jak można się spodziewać).

URL zasobu: http://yourserver.com/bigbluebutton/api/hooks/list?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Reakcja w przypadku zarejestrowania haków:

<response>
  <returncode>SUCCESS</returncode>
  <hooks>
    <hook>
      <hookID>12345678-1234-5678-1234-567812345678</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/abcdefghijk]]></callbackURL>
      <meetingID><![CDATA[my-meeting</meetingID]]>> <!-- a hook created for this meeting only -->
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
    <hook>
      <hookID>01234567-89ab-cdef-0123-456789abcdef</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/1234567890]]></callbackURL>
      <!-- no meetingID means this is a global hook -->
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
  </hooks>
</response>

Reakcja w przypadku braku zarejestrowanych haków:

<response>
  <returncode>SUCCESS</returncode>
  <hooks></hooks>
</response>

Format wywołania zwrotnego

Wszystkie zarejestrowane hooki są wywoływane poprzez HTTP POST ze wszystkimi informacjami o zdarzeniu w w treści tego żądania. Żądanie jest wysyłane z nagłówkiem HTTP Content-type ustawionym na application/x-www-form-urlencoded, a treść w treści ma następujący format (gdy getRaw=false):

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1415900488797

Atrybut timestamp oznacza znacznik czasu wykonania tego wywołania zwrotnego. Jeśli aplikacja web hook spróbuje wykonać wywołanie zwrotne i nie powiedzie się, spróbuje ponownie kilka razy, zawsze używając tego samego znacznika czasu. Sygnatury czasowe nigdy nie będą takie same dla różnych zdarzeń, a wartość będzie zawsze rosnąć.

Atrybut event jest skróconą wersją wszystkich danych ze zdarzenia (tak samo jak otrzymane z redis jeśli getRaw=true, przetworzone jeśli getRaw=false). Dane różnią się dla różnych typów zdarzeń . Więcej informacji znajdziesz w dokumentacji.

To jest przykład danych wysłanych w przypadku zdarzenia zniszczenia spotkania, gdy getRaw=false:

event={"data":{"type":"event","id":"meeting-ended","attributes":{"meeting":{"internal-meeting-id":"44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098","external-meeting-id":"random-3800337"}},"event":{"ts":1532718316938}}}
timestamp=1532718316953

To jest to samo zdarzenie dla innego haka z getRaw=true:

event={"envelope":{"name":"MeetingDestroyedEvtMsg","routing":{"sender":"bbb-apps-akka"}},"core":{"header":{"name":"MeetingDestroyedEvtMsg"},"body":{"meetingId":"44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098"}}}
timestamp=1532718316953

Ponadto wywołanie zwrotne jest podpisane sumą kontrolną, która jest zawarta w adresie URL żądania . Jeśli zarejestrowany adres URL to http://my-server.com/callback, otrzyma sumę kontrolną jak w http://my-server.com/callback?checksum=yalsdk18129e019iklasd90i.

Sposób tworzenia sumy kontrolnej jest podobny do sposobu obliczania sum kontrolnych dla innych wywołań API BigBlueButton.

sha<1|256|384|512>(<callback URL>+<data body>+<shared secret>)

Gdzie:

• <callback URL>: Oryginalny adres URL wywołania zwrotnego, który nie zawiera sumy kontrolnej.
• <data body as a string>: Wszystkie dane przesłane w treści żądania, połączone i połączone za pomocą &, tak jakby były parametrami w adresie URL.
• <shared secret>: Wspólny sekret serwera BigBlueButton.

Zatem po odebraniu wywołania zwrotnego aplikacja może sprawdzić sumę kontrolną w następujący sposób:

• Pobierz treść żądania, jak w przykładzie poniżej:

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1234567890

And convert it to a string like in the example below:

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1234567890

• Połącz oryginalny adres URL wywołania zwrotnego, ciąg z poprzedniego kroku i sól BigBlueButton.
• Oblicz sha<1|256|384|512>() tego ciągu.
• Obliczona suma kontrolna powinna być równa sumie kontrolnej otrzymanej w parametrach żądania.

Więcej szczegółów

• Wywołania zwrotne są zawsze uruchamiane dla jednego zdarzenia na raz i w odpowiedniej kolejności. Są uporządkowane w ten sam sposób, , w jakim pojawiają się na redis pubsub (kolejność może nie być dokładnie zgodna z ich sygnaturami czasowymi). Znaczniki czasu będą prawie zawsze zamawiane, ale nie jest to gwarantowane.
• Aplikacja zakłada, że ​​zdarzenia w pubsub nigdy nie są duplikowane. Jeśli zdarzy się, że zostaną zduplikowane , wywołania zwrotne również zostaną zduplikowane.
• Hooki są usuwane tylko wtedy, gdy wykonane zostanie wywołanie /hooks/destroy lub jeśli wywołania zwrotne dla hooka również zawiodą wiele razy (~12) przez długi okres czasu (~5min). W żaden inny sposób nie są one nigdy usuwane. Dotyczy zarówno haków globalnych, jak i haczyków przeznaczonych na określone spotkania. Dlatego w przypadku aplikacji innych firm, , zaleca się rejestrację hooków więcej niż raz. Możesz sprawdzić, czy Twój hak jest zarejestrowany w /hooks/list i zarejestrować go, jeśli nie jest, lub po prostu rejestrować swój hak co np. 5 minut.
• Aplikacja wykorzystuje wewnętrzne mapowania, aby dowiedzieć się, z jakim spotkaniem powiązane są zdarzenia otrzymane z redis . Te mapowania są usuwane po tygodniu braku aktywności. Jeżeli w tym okresie nie ma żadnych zdarzeń w dla danego spotkania, zostanie ono uznane za nieaktualne. Ma to na celu zapobieganie trwałemu przechowywaniu danych na Redis. Oznacza to, że możesz mieć problemy, jeśli masz hak zarejestrowany na konkretne spotkanie (nie zdarza się to w przypadku haków globalnych), a to spotkanie dzieje się, gdy nie generuje zdarzeń przez tydzień, ale po nim nadal jest ważne. Stało się coś bardzo, bardzo mało prawdopodobnego !
• Oczekuje się, że zewnętrzne adresy URL będą odpowiadać stanem HTTP 2xx (oczekiwanym domyślnym ustawieniem będzie 200). Wszystko, co różni się od tych wartości, zostanie uznane za błąd i wywołanie zwrotne zostanie ponownie wywołane . Obejmuje to przekierowania: jeśli Twój hak przekieruje żądanie, zostanie ono uznane za nieprawidłowe i aplikacja web hooków spróbuje ponownie wywołać ten hak.
• Jeśli spotkanie zostanie utworzone, gdy aplikacja web hooks nie będzie działać, wywołania zwrotne nigdy nie zostaną uruchomione. dla tego spotkania. Aplikacja musi wykryć zdarzenie tworzenia (meeting_created_message), aby miało odpowiednie mapowanie identyfikatorów spotkań wewnętrznych na zewnętrzne. Upewnij się więc, że aplikacja web hooków jest zawsze uruchomiona, gdy działa BigBlueButton!
• Jeśli zarejestrujesz hak z np. adresem URL http://myserver.com/my/hook i nie ustawisz meetingID (co stanie się hakiem globalnym), a później spróbujesz zarejestrować inny hak z tym samym adresem URL, ale z z zestawem meetingID, pierwszy hak nie zostanie usunięty ani zmodyfikowany, natomiast drugi hak nie zostanie utworzony.

Przetestuj

Najłatwiejszym sposobem przetestowania aplikacji web hooków jest zarejestrowanie hooków na serwerze BigBlueButton przy użyciu API Mate i przechwytywanie wywołań zwrotnych za pomocą Moduł wychwytujący POST innej firmy , taki jak webhook.site. W kodzie źródłowym bbb-webhooks dostępny jest również serwer testowy, którego można używać do przechwytywania haków, patrz: https://github.com/bigbluebutton/bbb-webhooks/blob/develop/extra/interceptor.js.

Postępuj zgodnie z instrukcjami:

• Otwórz wybrany moduł łapania webhooków i skopiuj jego adres URL punktu końcowego.
• Otwórz API Mate i skonfiguruj swój serwer oraz wspólny sekret.
• W menu „Parametry niestandardowe” znajduje się pole „Niestandardowe wywołania API:”. Dodaj do niego te wartości:

hooks/create
hooks/list

• W tej samej sekcji menu dodaj następujące wartości do „Parametry niestandardowe:”:

callbackURL=<your webhook catcher URL>

• W interfejsie API Mate kliknij link „wywołanie niestandardowe: hooks/create”. Powinien odpowiedzieć komunikatem o powodzeniu.
• W interfejsie API Mate kliknij link „wywołanie niestandardowe: hooks/list”, aby sprawdzić, czy Twój hak rzeczywiście został zarejestrowany w .
• Utwórz spotkanie i dołącz do niego za pomocą API Mate.
• Wykonuj różne czynności podczas spotkania i sprawdź punkt końcowy webhooka, aby sprawdzić, czy otrzymał wywołania zwrotne.

Rozwój

Zobacz dokumentację webhooków w GitHub.