Webhooks – Hændelser i realtid

BigBlueButton Webhooks lader din applikation modtage HTTP POST-notifikationer i realtid, hver gang mødehændelser opstår. I stedet for gentagne gange at polle getMeetings eller getMeetingInfo registrerer du en callback-URL, og BigBlueButton sender automatisk hændelser til dig. Dette kapitel dækker de tre webhook-API-endpoints, callback-formatet, hændelsestyper, retry-adfærd og serverkonfiguration.

Forudsætninger

Pakken bbb-webhooks skal være installeret på BigBlueButton-serveren, før webhook-endpoints bliver tilgængelige:

sudo apt-get install bbb-webhooks

hooks/create — registrér en webhook

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

Vellykket svar

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

Dubletregistrering

Hvis den samme callbackURL registreres igen, returnerer svaret stadig SUCCESS, men inkluderer en duplicateWarning. Det eksisterende hook bevares uændret — meetingID, eventID og getRaw opdateres ikke.

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

Fejlsvar

hooks/list — vis registrerede webhooks

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

Vellykket svar

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

Fejlsvar

hooks/destroy — fjern en webhook

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

Vellykket svar

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

Fejlsvar

hooks/ping — health check

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

Dette diagnostiske endpoint kræver ingen checksum. Hvis webhook-applikationen kan nås, returnerer det klartekststrengen bbb-webhooks API up! (ikke XML, indholdstype text/plain). undocumented

Callback-format

Webhook-callbacks sendes som HTTP POST-anmodninger med indholdstypen application/x-www-form-urlencoded. Anmodningens brødtekst indeholder tre felter:

Behandlet callback-body (getRaw=false)

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

Rå callback-body (getRaw=true)

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

Validering af callback-checksum

I standardtilstand modtager hver callback-URL en query-parameter checksum, som din applikation bør verificere:

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

Valideringsformlen er:

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

Auth 2.0 / Bearer-tilstand

Alternativt kan serveren konfigureres med auth2_0: true. I denne tilstand føjes ingen checksum-parameter til callback-URL'en. I stedet sendes shared secret som en Bearer-token i headeren Authorization: undocumented

Authorization: Bearer <shared-secret>

Callback-adfærd

• Accepterede HTTP-statuskoder: HTTP 2xx og HTTP 401 behandles som succesfuld levering. Alle andre statuskoder udløser et retry. undocumented
• Redirects: HTTP 3xx-svar følges (op til 10 hop). Kun hvis ingen 2xx/401 nås efter 10 redirects, tæller callbacken som mislykket.
• Timeout: Hver callback-anmodning har en timeout på 5 sekunder (kan konfigureres via requestTimeout).
• Genforsøgsintervaller: Ved fejl bruger genforsøg eksponentiel back-off: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 forsøg over cirka 5 minutter, kan konfigureres via retryIntervals).
• Når alle genforsøg er opbrugt: Ikke-permanente hooks fjernes automatisk. Permanente hooks fortsætter med at prøve igen på ubestemt tid med 60-sekunders intervaller (kan konfigureres via permanentIntervalReset).

Hændelsestyper

Mødehændelser

Brugerhændelser

Chat- og notehændelser

Afstemningshændelser

Optagelses- og afspilningshændelser (RAP)

Serverkonfiguration

Følgende indstillinger kan konfigureres i /etc/bigbluebutton/bbb-webhooks.yml eller config/default.yml. De fleste af disse indstillinger er ikke dækket i den officielle dokumentation. undocumented

Driftsbemærkninger

• Persistens: Hooks gemmes i Redis og overlever servergenstarter (gensynkroniseres ved opstart).
• Rækkefølge: Callbacks sendes sekventielt pr. hook, én ad gangen, så hændelsesrækkefølgen bevares.
• URL-unikhed: Dubletdetektion er udelukkende baseret på callback-URL'en. Den samme URL kan ikke registreres med forskellige meetingID- eller eventID-filtre — den første registrering vinder.
• Dataoprydning: Interne mødetilknytninger fjernes efter én uges inaktivitet (kan konfigureres via mappings.timeout, standard: 604800000 ms).
• Syntetiske hændelser: Når et møde afsluttes, genereres user-left-hændelser automatisk for alle stadig tilsluttede brugere, fordi BigBlueButton selv ikke udsender UserLeftMeetingEvtMsg ved mødets afslutning.
• Private chats: Kun offentlige chatbeskeder genererer chat-group-message-sent-hændelser. Private beskeder ignoreres uden varsel.