Webhooks – Eventi in tempo reale

I Webhook di BigBlueButton permettono alla tua applicazione di ricevere notifiche HTTP POST in tempo reale ogni volta che si verificano eventi di riunione. Invece di interrogare ripetutamente getMeetings o getMeetingInfo, registri un URL di callback e BigBlueButton ti invia automaticamente gli eventi. Questo capitolo copre i tre endpoint API dei webhook, il formato della callback, i tipi di evento, il comportamento di retry e la configurazione del server.

Prerequisiti

Il pacchetto bbb-webhooks deve essere installato sul server BigBlueButton prima che gli endpoint webhook diventino disponibili:

sudo apt-get install bbb-webhooks

hooks/create — Registra un webhook

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

Risposta riuscita

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

Registrazione duplicata

Se lo stesso callbackURL viene registrato di nuovo, la risposta restituisce comunque SUCCESS ma include un duplicateWarning. L'hook esistente viene mantenuto invariato — meetingID, eventID e getRaw non vengono aggiornati.

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

Risposte di errore

hooks/list — Elenca i webhook registrati

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

Risposta riuscita

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

Risposte di errore

hooks/destroy — Rimuovi un webhook

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

Risposta riuscita

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

Risposte di errore

hooks/ping — Controllo di integrità

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

Questo endpoint diagnostico non richiede checksum. Se l'applicazione webhook è raggiungibile, restituisce la stringa in testo semplice bbb-webhooks API up! (non XML, tipo di contenuto text/plain). undocumented

Formato del callback

I callback webhook vengono inviati come richieste HTTP POST con tipo di contenuto application/x-www-form-urlencoded. Il corpo della richiesta contiene tre campi:

Corpo della callback elaborato (getRaw=false)

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

Corpo della callback grezzo (getRaw=true)

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

Convalida del checksum del callback

Nella modalità predefinita, ogni URL di callback riceve un parametro di query checksum che la tua applicazione dovrebbe verificare:

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

La formula di convalida è:

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

Modalità Auth 2.0 / Bearer

In alternativa, il server può essere configurato con auth2_0: true. In questa modalità, nessun parametro checksum viene aggiunto all'URL di callback. Invece, il shared secret viene inviato come token Bearer nell'header Authorization: undocumented

Authorization: Bearer <shared-secret>

Comportamento del callback

• Codici di stato HTTP accettati: HTTP 2xx e HTTP 401 vengono trattati come consegna riuscita. Tutti gli altri codici di stato attivano un retry. undocumented
• Redirect: Le risposte HTTP 3xx vengono seguite (fino a 10 hop). Solo se non si raggiunge alcun 2xx/401 dopo 10 redirect la callback viene considerata fallita.
• Timeout: ogni richiesta di callback ha un timeout di 5 secondi (configurabile tramite requestTimeout).
• Intervalli di ritentativo: in caso di errore, i ritentativi usano back-off esponenziale: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 tentativi in circa 5 minuti, configurabile tramite retryIntervals).
• Dopo l'esaurimento di tutti i ritentativi: i hook non permanenti vengono rimossi automaticamente. I hook permanenti continuano a ritentare indefinitamente a intervalli di 60 secondi (configurabile tramite permanentIntervalReset).

Tipi di evento

Eventi della riunione

Eventi utente

Eventi della chat e delle note

Eventi dei sondaggi

Eventi Record and Playback (RAP)

Configurazione del server

Le seguenti opzioni possono essere configurate in /etc/bigbluebutton/bbb-webhooks.yml o config/default.yml. La maggior parte di queste opzioni non è coperta dalla documentazione ufficiale. undocumented

Note operative

• Persistenza: Gli hook sono memorizzati in Redis e sopravvivono ai riavvii del server (risincronizzati all'avvio).
• Ordinamento: I callback vengono inviati in modo sequenziale per hook, uno alla volta, preservando l'ordine degli eventi.
• Unicità URL: Il rilevamento dei duplicati si basa esclusivamente sull'URL di callback. Lo stesso URL non può essere registrato con filtri meetingID o eventID diversi — prevale la prima registrazione.
• Pulizia dei dati: Le mappature interne delle riunioni vengono rimosse dopo una settimana di inattività (configurabile tramite mappings.timeout, predefinito: 604800000 ms).
• Eventi sintetici: Quando una riunione termina, gli eventi user-left vengono generati automaticamente per tutti gli utenti ancora connessi, perché BigBlueButton stesso non emette UserLeftMeetingEvtMsg alla fine della riunione.
• Chat private: Solo i messaggi della chat pubblica generano eventi chat-group-message-sent. I messaggi privati vengono ignorati silenziosamente.