API-Version: 4.x neueste 3.x

Sie sehen die API-Dokumentation für BigBlueButton 3.x. Die aktuelle Version ist BigBlueButton 4.x. Planen Sie ein Upgrade? Der Migrationsleitfaden listet alle erforderlichen Änderungen an Ihren API-Aufrufen auf.

Kapitel 17 GET

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.

Webhooks erfordern, dass das Paket bbb-webhooks auf dem Server installiert ist. Mehrere in diesem Kapitel beschriebene Details werden in der offiziellen BigBlueButton-Dokumentation nicht behandelt und wurden durch Quellcodeanalyse ermittelt. undocumented

Voraussetzungen

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

sudo apt-get install bbb-webhooks

Wenn die Webhook-Anwendung beim Erstellen eines Meetings nicht läuft, erfährt sie dessen externe ID nie. Für dieses Meeting registrierte Hooks (mit meetingID) werden nicht ausgelöst, und bei Ereignissen, die an globale Hooks übermittelt werden, fehlt external-meeting-id.

hooks/create — Einen Webhook registrieren

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

Die offizielle Dokumentation gibt keine HTTP-Methode an. Der Express-Router registriert nur GET-Routen — POST-Anfragen werden nicht akzeptiert. undocumented

Parameter Typ Erforderlich Standard Beschreibung
callbackURL String Ja — Die URL, die POST-Callbacks empfangen wird. Die Duplikaterkennung basiert ausschließlich auf dieser URL — dieselbe URL kann nicht zweimal registriert werden, auch nicht mit einem anderen meetingID oder eventID.
meetingID String Nein — Beschränkt den Hook auf ein bestimmtes Meeting (externe Meeting-ID). Wenn weggelassen, wird der Hook zu einem globalen Hook, der für alle Meetings ausgelöst wird.
eventID String Nein — Kommagetrennte Liste von Ereignistypen, auf die gehört werden soll (z. B. user-joined,meeting-ended). Wenn weggelassen, werden alle Ereignisse zugestellt. Der Filter ist nicht case-sensitiv. Verfügbar seit BBB 2.5.
getRaw Boolean Nein false Wenn auf true gesetzt, enthalten Callbacks die rohe Redis-Nachricht statt der verarbeiteten Ereignisdaten.

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

messageKey Beschreibung
checksumError Die Checksum ist ungültig oder fehlt.
missingParamCallbackURL Der Parameter callbackURL wurde nicht angegeben. undocumented
createHookError Es ist ein interner Fehler aufgetreten (z. B. Redis nicht erreichbar). Prüfen Sie die Server-Logs.

hooks/list — Registrierte Webhooks auflisten

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/list?<parameters>&checksum=replace-with-checksum
Parameter Typ Erforderlich Beschreibung
meetingID String Nein Filtert nach Meeting-ID. Das Ergebnis enthält sowohl Hooks für das angegebene Meeting als auch alle globalen Hooks. Wenn weggelassen, werden alle registrierten Hooks zurückgegeben.

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>

Das Element <meetingID> erscheint nur bei Meeting-spezifischen Hooks. Globale Hooks haben kein Element <meetingID>. Ebenso erscheint <eventID> nur, wenn bei der Erstellung ein Ereignisfilter gesetzt wurde.

Fehlerantworten

messageKey Beschreibung
checksumError Die Checksum ist ungültig oder fehlt.
listHookError Beim Auflisten der Hooks ist ein interner Fehler aufgetreten. Prüfen Sie die Server-Logs. undocumented

hooks/destroy — Einen Webhook entfernen

GET https://api-guide.bbbserver.com/bigbluebutton/api/hooks/destroy?<parameters>&checksum=replace-with-checksum
Parameter Typ Erforderlich Beschreibung
hookID String Ja Die ID des zu entfernenden Hooks (erhalten von hooks/create oder hooks/list).

Erfolgreiche Antwort

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

Permanente Hooks (serverseitig über permanentURLs konfiguriert) können nicht über die API gelöscht werden. Ein entsprechender Versuch liefert einen Fehler destroyMissingHook zurück, als ob der Hook nicht existieren würde.

Fehlerantworten

messageKey Beschreibung
checksumError Die Checksum ist ungültig oder fehlt.
missingParamHookID Der Parameter hookID wurde nicht angegeben.
destroyMissingHook Die Hook-ID existiert nicht oder gehört zu einem permanenten Hook.
destroyHookError Beim Entfernen des Hooks ist ein interner Fehler aufgetreten. Prüfen Sie die Server-Logs.

hooks/ping — Health-Check

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

Dieser Diagnose-Endpunkt erfordert keine Prüfsumme. Wenn die Webhook-Anwendung erreichbar ist, gibt er die einfache Zeichenfolge bbb-webhooks API up! zurück (kein XML). 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:

Feld Beschreibung
domain Die Server-Domain (aus der Webhook-Konfiguration). undocumented
event Ein JSON-Array, das die Ereignisdaten enthält. Immer ein Array, auch bei nur einem einzelnen Ereignis.
timestamp Ein Unix-Zeitstempel in Millisekunden zum Zeitpunkt des Versands.

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

Die Beispielkonfiguration enthält eine Option multiEvent, die vom Code jedoch nicht ausgewertet wird: Jeder Callback enthält genau ein Ereignis im Array event.

Validierung der Callback-Prüfsumme

Sofern bbb.auth2_0 nicht aktiviert ist (siehe unten), erhält jede Callback-URL einen Abfrageparameter 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>)

Nehmen Sie die registrierte Callback-URL ohne den Prüfsummen-Parameter.

Hängen Sie den vollständig URL-kodierten Request-Body (domain=...&event=[...]&timestamp=...) an.

Hängen Sie das BBB Shared Secret an.

Hashen Sie die resultierende Zeichenfolge mit dem konfigurierten Algorithmus (Standard: sha1, konfigurierbar über hookChecksumAlgorithm).

Auth 2.0 / Bearer-Modus

Mit auth2_0: true wird kein Prüfsummenparameter an die Callback-URL angehängt. Stattdessen wird das gemeinsame Geheimnis als Bearer-Token im Header Authorization gesendet. Das Paket bbb-webhooks aktiviert diesen Modus während der Installation, sodass er auf standardmäßig eingerichteten BigBlueButton-Servern die Voreinstellung ist: 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 erfolgen die Wiederholungsversuche mit exponentiell zunehmenden Wartezeiten: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 Wiederholungsversuche über etwa 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

Ereignis-ID Beschreibung
meeting-created Ein Meeting wurde erstellt.
meeting-ended Ein Meeting wurde beendet. Dies löst außerdem synthetische user-left-Ereignisse für alle verbundenen Benutzer aus.
meeting-recording-started Die Aufzeichnung wurde gestartet.
meeting-recording-stopped Die Aufzeichnung wurde gestoppt.
meeting-recording-unhandled In der Liste der Ereignis-IDs deklariert, aber nie erzeugt: Ein Aufzeichnungsstatus, der weder true noch false ist, erzeugt kein verwertbares Ereignis.
meeting-screenshare-started Die Bildschirmfreigabe wurde gestartet (einschließlich Presenter-Benutzerdaten).
meeting-screenshare-stopped Die Bildschirmfreigabe wurde beendet (einschließlich Eigentümer-Benutzerdaten).
meeting-presentation-changed Die aktive Präsentation wurde geändert (einschließlich presentation-id).

Benutzerereignisse

Ereignis-ID Beschreibung
user-joined Ein Benutzer ist dem Meeting beigetreten (enthält Gast-Flag, Benutzerdaten, IP-Adresse, User-Agent).
user-left Ein Benutzer hat das Meeting verlassen (einschließlich Gast-Flag). Wird auch bei meeting-ended synthetisch erzeugt.
user-audio-voice-enabled Audio aktiviert (enthält listening-only-, sharing-mic-, muted-Flags).
user-audio-voice-disabled Audio deaktiviert.
user-audio-muted Benutzer wurde stummgeschaltet.
user-audio-unmuted Stummschaltung des Benutzers wurde aufgehoben.
user-audio-unhandled Nicht behandeltes Audioereignis (Fallback).
user-cam-broadcast-start Webcam gestartet (enthält stream).
user-cam-broadcast-end Webcam gestoppt.
user-presenter-assigned Benutzer wurde die Präsentatorrolle zugewiesen.
user-presenter-unassigned Benutzer wurde aus der Präsentatorrolle entfernt.
user-emoji-changed Benutzer-Emoji oder -Reaktion geändert (einschließlich Emoji-Wert).
user-raise-hand-changed Benutzer hat die Hand gehoben oder gesenkt (enthält raise-hand-Boolean). In BBB-Versionen vor 2.7 wird dies synthetisch aus user-emoji-changed erzeugt.

Chat- und Notizereignisse

Ereignis-ID Beschreibung
chat-group-message-sent Eine Nachricht wurde im öffentlichen Chat gesendet. Private Chat-Nachrichten erzeugen keine Webhook-Ereignisse.
transcript-updated Transkription aktualisiert (enthält transcript, locale, final-Flag).
pad-content Inhalt der geteilten Notizen geändert (enthält pad.id, pad.rev, pad.text).

Umfrageereignisse

Ereignis-ID Beschreibung
poll-started Eine Umfrage wurde gestartet (einschließlich Frage und Antwortoptionen).
poll-responded Ein Teilnehmer hat auf eine Umfrage geantwortet (einschließlich Antwort-IDs).

Aufnahme- und Wiedergabeereignisse (RAP)

Ereignis-ID Beschreibung
rap-archive-started Archivierung gestartet.
rap-archive-ended Archivierung abgeschlossen (enthält recorded-Flag und Dauer).
rap-sanity-started Integritätsprüfung gestartet.
rap-sanity-ended Integritätsprüfung abgeschlossen.
rap-post-archive-started Nacharchivierung gestartet.
rap-post-archive-ended Nacharchivierung abgeschlossen.
rap-process-started Verarbeitung gestartet.
rap-process-ended Verarbeitung abgeschlossen.
rap-post-process-started Nachverarbeitung gestartet.
rap-post-process-ended Nachverarbeitung abgeschlossen.
rap-publish-started Veröffentlichung gestartet.
rap-publish-ended Veröffentlichung abgeschlossen (einschließlich vollständigem Aufnahmeobjekt mit Metadaten, Wiedergabe- und Download-Informationen).
rap-post-publish-started Nachveröffentlichung gestartet.
rap-post-publish-ended Nachveröffentlichung abgeschlossen.
rap-published Aufnahme veröffentlicht.
rap-unpublished Veröffentlichung der Aufnahme aufgehoben.
rap-deleted Aufnahme gelöscht.

Die meisten RAP-Ereignisse enthalten record-id, success (Boolean) und step-time. Ereignisse mit einem workflow-Feld enthalten zusätzlich den Namen des Verarbeitungs-Workflows.

Serverkonfiguration

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

Option Standard Beschreibung
hookChecksumAlgorithm sha1 Hash-Algorithmus für Callback-Checksummen (sha1, sha256, sha384, sha512).
api.supportedChecksumAlgorithms [sha1, sha256, sha384, sha512] Akzeptierte Algorithmen für eingehende API-Prüfsummen.
api.port 3005 Port des Webhook-API-Servers.
api.bind 127.0.0.1 Bind-Adresse des API-Servers.
includeEvents [] Serverweiter Ereignisfilter: Nur diese Ereignisse werden an alle Hooks ausgeliefert. Leer bedeutet alle Ereignisse.
excludeEvents [] Serverweiter Ereignisfilter: Diese Ereignisse werden für alle Hooks unterdrückt. Leer bedeutet keine Ausschlüsse.
permanentURLs [] Liste permanenter Hook-URLs, die beim Start registriert werden und nicht über die API entfernt werden können.
retryIntervals [100,500,1000,...,60000] Wiederholungsintervalle in Millisekunden für fehlgeschlagene Callbacks.
permanentIntervalReset 60000 Wiederholungsintervall in Millisekunden für permanente Hooks, nachdem alle regulären Wiederholungen ausgeschöpft sind.
requestTimeout 5000 HTTP-Timeout in Millisekunden für Callback-Anfragen.
multiEvent 1 In der Beispielkonfiguration vorhanden, wird vom Code jedoch nicht ausgewertet.
queueSize 10000 In der Beispielkonfiguration vorhanden, wird vom Code jedoch nicht ausgewertet.
bbb.auth2_0 false Aktiviert die Authentifizierung mit Bearer-Token anstelle einer URL-Prüfsumme für Callbacks. Das Paket bbb-webhooks setzt diese Option während der Installation auf true.

includeEvents und excludeEvents sind serverweite Filter, die zusätzlich zum pro Hook definierten eventID-Filter gelten. Ein Ereignis muss beide Filter bestehen, um zugestellt zu werden.

Betriebshinweise

  • Persistenz: Hooks werden in Redis gespeichert und überstehen Server-Neustarts (beim Start erneut synchronisiert).
  • Reihenfolge: Jedes Ereignis wird unabhängig von anderen versendet und bei Fehlern erneut zugestellt. Daher ist nicht garantiert, dass Callbacks in der Reihenfolge der Ereignisse eintreffen (insbesondere nach fehlgeschlagenen Versuchen). Verwenden Sie den Ereigniszeitstempel event.ts, um die Ereignisse zu sortieren.
  • 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.
Auf bbbserver.de sind Webhooks mit zwei Einschränkungen verfügbar: (1) Für jeden Hook ist meetingID erforderlich — globale Hooks ohne meetingID werden nicht unterstützt; (2) Ereignisse werden gefiltert: Teilnehmerdaten wie der Name, external-user-id, der User-Agent und userdata-Parameter werden im Klartext weitergegeben, alle anderen Felder (z. B. IP-Adressen der Teilnehmer) werden entfernt.

Häufig gestellte Fragen

Ja. Das Paket bbb-webhooks muss über apt-get install bbb-webhooks installiert werden. Ohne dieses sind die Endpunkte hooks/create, hooks/list und hooks/destroy nicht verfügbar.

Das Webhook-System wiederholt die Zustellung mit exponentiell zunehmenden Wartezeiten über etwa 5 Minuten (12 Wiederholungsversuche). Wenn alle Wiederholungsversuche fehlschlagen, werden nicht permanente Hooks automatisch entfernt. Permanente Hooks setzen die Wiederholungsversuche unbegrenzt in Intervallen von 60 Sekunden fort.

Nein. Die Duplikaterkennung basiert ausschließlich auf der Callback-URL. Wenn Sie dieselbe URL erneut registrieren, erhalten Sie duplicateWarning und der bestehende Hook bleibt unverändert. Um bestimmte Meetings getrennt zu überwachen, verwenden Sie unterschiedliche Callback-URLs.

Nein. Nur Nachrichten, die an den öffentlichen Chat (MAIN-PUBLIC-GROUP-CHAT) gesendet werden, lösen ein Ereignis chat-group-message-sent aus. Private Nachrichten zwischen Teilnehmern erzeugen keine Webhook-Ereignisse.

Mit getRaw=false (dem Standard) erhalten Sie verarbeitete Ereignisdaten mit einer standardisierten Struktur, die die Felder type, id und attributes enthält. Mit getRaw=true erhalten Sie die rohe Redis-Nachricht, wie sie intern von BigBlueButton veröffentlicht wird, einschließlich der Felder envelope und core. Das Rohformat ist nützlich für Debugging oder wenn Sie Daten benötigen, die im verarbeiteten Format nicht enthalten sind.

Nein. Permanente Hooks werden serverseitig über die Einstellung permanentURLs konfiguriert und können nicht über die API entfernt werden. Ein Aufruf von hooks/destroy für einen permanenten Hook gibt einen Fehler destroyMissingHook zurück, als ob der Hook nicht existieren würde.

HTTP 2xx und HTTP 401 werden beide als erfolgreiche Zustellung behandelt. Alle anderen Statuscodes, einschließlich 3xx (nach bis zu 10 Weiterleitungen), 4xx (außer 401) und 5xx, lösen einen Wiederholungsversuch aus. Dieses Verhalten ist in der offiziellen BigBlueButton-Dokumentation nicht dokumentiert.