Webhooks – Echtzeit-Ereignisse

BigBlueButton-Webhooks ermöglichen Ihrer Anwendung, HTTP-POST-Benachrichtigungen in Echtzeit zu empfangen, sobald Meeting-Ereignisse auftreten. Anstatt wiederholt getMeetings oder getMeetingInfo abzufragen, registrieren Sie eine Callback-URL und BigBlueButton pusht die Ereignisse automatisch an Sie. Dieses Kapitel behandelt die drei Webhook-API-Endpunkte, das Callback-Format, Ereignistypen, Wiederholungsverhalten und die Serverkonfiguration.

Voraussetzungen

Das Paket bbb-webhooks muss auf dem BigBlueButton-Server installiert sein, bevor Webhook-Endpunkte verfügbar werden:

sudo apt-get install bbb-webhooks

hooks/create — Einen Webhook registrieren

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

Erfolgreiche Antwort

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

Doppelte Registrierung

Wenn dieselbe callbackURL erneut registriert wird, gibt die Antwort weiterhin SUCCESS zurück, enthält jedoch eine duplicateWarning. Der vorhandene Hook bleibt unverändert — meetingID, eventID und getRaw werden nicht aktualisiert.

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

Fehlerantworten

hooks/list — Registrierte Webhooks auflisten

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

Erfolgreiche Antwort

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

Fehlerantworten

hooks/destroy — Einen Webhook entfernen

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

Erfolgreiche Antwort

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

Fehlerantworten

hooks/ping — Health-Check

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

Dieser Diagnose-Endpunkt benötigt keine Prüfsumme. Wenn die Webhook-Anwendung erreichbar ist, gibt er die Klartext-Zeichenfolge bbb-webhooks API up! zurück (nicht XML, Content-Type text/plain). undocumented

Callback-Format

Webhook-Callbacks werden als HTTP-POST-Anfragen mit dem Content-Type application/x-www-form-urlencoded gesendet. Der Request-Body enthält drei Felder:

Verarbeiteter Callback-Body (getRaw=false)

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

Roher Callback-Body (getRaw=true)

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

Validierung der Callback-Prüfsumme

Im Standardmodus erhält jede Callback-URL einen Query-Parameter checksum, den Ihre Anwendung überprüfen sollte:

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

Die Validierungsformel lautet:

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

Auth 2.0 / Bearer-Modus

Alternativ kann der Server mit auth2_0: true konfiguriert werden. In diesem Modus wird kein Checksum-Parameter an die Callback-URL angehängt. Stattdessen wird das Shared Secret als Bearer-Token im Header Authorization gesendet: undocumented

Authorization: Bearer <shared-secret>

Callback-Verhalten

• Akzeptierte HTTP-Statuscodes: HTTP 2xx und HTTP 401 werden als erfolgreiche Zustellung behandelt. Alle anderen Statuscodes lösen einen Wiederholungsversuch aus. undocumented
• Weiterleitungen: HTTP-3xx-Antworten wird gefolgt (bis zu 10 Sprünge). Erst wenn nach 10 Weiterleitungen kein 2xx/401 erreicht wird, gilt der Callback als fehlgeschlagen.
• Timeout: Jede Callback-Anfrage hat ein Timeout von 5 Sekunden (konfigurierbar über requestTimeout).
• Wiederholungsintervalle: Bei einem Fehler verwenden Wiederholungen exponentielles Back-off: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 Versuche über ungefähr 5 Minuten, konfigurierbar über retryIntervals).
• Nachdem alle Wiederholungen ausgeschöpft sind: Nicht permanente Hooks werden automatisch entfernt. Permanente Hooks versuchen die Zustellung weiterhin unbegrenzt in 60-Sekunden-Intervallen (konfigurierbar über permanentIntervalReset).

Ereignistypen

Meeting-Ereignisse

Benutzerereignisse

Chat- und Notizereignisse

Umfrageereignisse

Aufnahme- und Wiedergabeereignisse (RAP)

Serverkonfiguration

Die folgenden Optionen können in /etc/bigbluebutton/bbb-webhooks.yml oder config/default.yml konfiguriert werden. Die meisten dieser Optionen werden in der offiziellen Dokumentation nicht behandelt. undocumented

Betriebshinweise

• Persistenz: Hooks werden in Redis gespeichert und überstehen Server-Neustarts (beim Start erneut synchronisiert).
• Reihenfolge: Callbacks werden pro Hook nacheinander gesendet, jeweils einer nach dem anderen, wobei die Ereignisreihenfolge erhalten bleibt.
• URL-Eindeutigkeit: Die Duplikaterkennung basiert ausschließlich auf der Callback-URL. Dieselbe URL kann nicht mit unterschiedlichen meetingID- oder eventID-Filtern registriert werden — die erste Registrierung gewinnt.
• Datenbereinigung: Interne Meeting-Zuordnungen werden nach einer Woche Inaktivität entfernt (konfigurierbar über mappings.timeout, Standard: 604800000 ms).
• Synthetische Ereignisse: Wenn ein Meeting endet, werden user-left-Ereignisse automatisch für alle noch verbundenen Benutzer erzeugt, weil BigBlueButton selbst bei Meeting-Ende keine UserLeftMeetingEvtMsg ausgibt.
• Private Chats: Nur öffentliche Chatnachrichten erzeugen chat-group-message-sent-Ereignisse. Private Nachrichten werden stillschweigend ignoriert.