Webhooks – Realtimegebeurtenissen

BigBlueButton Webhooks zorgen ervoor dat je applicatie realtime HTTP-POST-meldingen ontvangt wanneer vergadergebeurtenissen plaatsvinden. In plaats van herhaaldelijk getMeetings of getMeetingInfo te pollen, registreer je een callback-URL en pusht BigBlueButton automatisch gebeurtenissen naar je toe. Dit hoofdstuk behandelt de drie webhook-API-endpoints, het callbackformaat, gebeurtenistypen, retrygedrag en serverconfiguratie.

Vereisten

Het pakket bbb-webhooks moet op de BigBlueButton-server zijn geïnstalleerd voordat webhook-endpoints beschikbaar worden:

sudo apt-get install bbb-webhooks

hooks/create — Een webhook registreren

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

Succesvolle respons

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

Dubbele registratie

Als dezelfde callbackURL opnieuw wordt geregistreerd, retourneert de respons nog steeds SUCCESS maar bevat deze een duplicateWarning. De bestaande hook blijft ongewijzigd — meetingID, eventID en getRaw worden niet bijgewerkt.

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

Foutresponses

hooks/list — Geregistreerde webhooks weergeven

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

Succesvolle respons

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

Foutresponses

hooks/destroy — Een webhook verwijderen

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

Succesvolle respons

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

Foutresponses

hooks/ping — Gezondheidscontrole

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

Dit diagnostische endpoint vereist geen checksum. Als de webhookapplicatie bereikbaar is, retourneert het de platte-tekststring bbb-webhooks API up! (geen XML, contenttype text/plain). undocumented

Callback-indeling

Webhook-callbacks worden verzonden als HTTP POST-verzoeken met contenttype application/x-www-form-urlencoded. De requestbody bevat drie velden:

Verwerkte callbackbody (getRaw=false)

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

Ruwe callbackbody (getRaw=true)

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

Validatie van callback-checksum

In de standaardmodus ontvangt elke callback-URL een queryparameter checksum die je applicatie moet verifiëren:

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

De validatieformule is:

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

Auth 2.0 / Bearer-modus

Als alternatief kan de server worden geconfigureerd met auth2_0: true. In deze modus wordt er geen checksum-parameter aan de callback-URL toegevoegd. In plaats daarvan wordt het shared secret verzonden als een Bearer-token in de header Authorization: undocumented

Authorization: Bearer <shared-secret>

Callback-gedrag

• Geaccepteerde HTTP-statuscodes: HTTP 2xx en HTTP 401 worden als succesvolle aflevering beschouwd. Alle andere statuscodes activeren een retry. undocumented
• Redirects: HTTP-3xx-responses worden gevolgd (tot 10 hops). Alleen als er na 10 redirects geen 2xx/401 wordt bereikt, geldt de callback als mislukt.
• Timeout: Elk callback-verzoek heeft een timeout van 5 seconden (configureerbaar via requestTimeout).
• Interval tussen nieuwe pogingen: Bij een fout gebruiken retries exponentiële back-off: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 pogingen over ongeveer 5 minuten, configureerbaar via retryIntervals).
• Nadat alle nieuwe pogingen zijn uitgeput: Niet-permanente hooks worden automatisch verwijderd. Permanente hooks blijven onbeperkt opnieuw proberen met intervallen van 60 seconden (configureerbaar via permanentIntervalReset).

Gebeurtenistypen

Vergaderingsgebeurtenissen

Gebruikersgebeurtenissen

Chat- en notitiegebeurtenissen

Pollgebeurtenissen

Opname- en afspeelgebeurtenissen (RAP)

Serverconfiguratie

De volgende opties kunnen worden geconfigureerd in /etc/bigbluebutton/bbb-webhooks.yml of config/default.yml. De meeste van deze opties worden niet behandeld in de officiële documentatie. undocumented

Operationele opmerkingen

• Persistentie: Hooks worden opgeslagen in Redis en overleven serverherstarts (opnieuw gesynchroniseerd bij het opstarten).
• Volgorde: Callbacks worden per hook sequentieel verzonden, één tegelijk, waarbij de gebeurtenisvolgorde behouden blijft.
• Uniciteit van URL's: Detectie van duplicaten is uitsluitend gebaseerd op de callback-URL. Dezelfde URL kan niet worden geregistreerd met verschillende meetingID- of eventID-filters — de eerste registratie wint.
• Opschonen van gegevens: Interne meetingtoewijzingen worden verwijderd na één week inactiviteit (configureerbaar via mappings.timeout, standaard: 604800000 ms).
• Synthetische gebeurtenissen: Wanneer een vergadering eindigt, worden voor alle nog verbonden gebruikers automatisch user-left-gebeurtenissen gegenereerd, omdat BigBlueButton zelf geen UserLeftMeetingEvtMsg uitzendt bij het einde van een vergadering.
• Privéchats: Alleen openbare chatberichten genereren chat-group-message-sent-gebeurtenissen. Privéberichten worden stilzwijgend genegeerd.