Webhooks – Événements en temps réel

Les webhooks BigBlueButton permettent à votre application de recevoir des notifications HTTP POST en temps réel chaque fois que des événements de réunion se produisent. Au lieu d’interroger en boucle getMeetings ou getMeetingInfo, vous enregistrez une URL de callback et BigBlueButton vous envoie automatiquement les événements. Ce chapitre couvre les trois points de terminaison API de webhook, le format des callbacks, les types d’événements, le comportement de nouvelle tentative et la configuration du serveur.

Prérequis

Le package bbb-webhooks doit être installé sur le serveur BigBlueButton avant que les points de terminaison webhook deviennent disponibles :

sudo apt-get install bbb-webhooks

hooks/create — Enregistrer un webhook

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

Réponse réussie

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

Enregistrement en double

Si le même callbackURL est enregistré à nouveau, la réponse renvoie toujours SUCCESS mais inclut un duplicateWarning. Le hook existant est conservé sans modification — meetingID, eventID et getRaw ne sont pas mis à jour.

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

Réponses d’erreur

hooks/list — Lister les webhooks enregistrés

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

Réponse réussie

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

Réponses d’erreur

hooks/destroy — Supprimer un webhook

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

Réponse réussie

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

Réponses d’erreur

hooks/ping — Vérification de l’état

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

Ce point de terminaison de diagnostic ne nécessite aucune somme de contrôle. Si l’application webhook est joignable, il renvoie la chaîne en texte brut bbb-webhooks API up! (pas du XML, type de contenu text/plain). undocumented

Format du callback

Les callbacks webhook sont envoyés sous forme de requêtes HTTP POST avec le type de contenu application/x-www-form-urlencoded. Le corps de la requête contient trois champs :

Corps du callback traité (getRaw=false)

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

Corps du callback brut (getRaw=true)

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

Validation de la somme de contrôle du callback

Dans le mode par défaut, chaque URL de callback reçoit un paramètre de requête checksum que votre application doit vérifier :

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

La formule de validation est :

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

Mode Auth 2.0 / Bearer

Alternativement, le serveur peut être configuré avec auth2_0: true. Dans ce mode, aucun paramètre checksum n’est ajouté à l’URL de callback. À la place, le secret partagé est envoyé comme jeton Bearer dans l’en-tête Authorization : undocumented

Authorization: Bearer <shared-secret>

Comportement du callback

• Codes de statut HTTP acceptés : HTTP 2xx et HTTP 401 sont traités comme une livraison réussie. Tous les autres codes de statut déclenchent une nouvelle tentative. undocumented
• Redirections : Les réponses HTTP 3xx sont suivies (jusqu’à 10 sauts). Ce n’est que si aucun 2xx/401 n’est atteint après 10 redirections que le callback est considéré comme ayant échoué.
• Délai d’expiration : chaque requête de callback a un délai d’expiration de 5 secondes (configurable via requestTimeout).
• Intervalles de nouvelle tentative : en cas d’échec, les nouvelles tentatives utilisent un back-off exponentiel : 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 tentatives sur environ 5 minutes, configurable via retryIntervals).
• Après l’épuisement de toutes les tentatives : les hooks non permanents sont supprimés automatiquement. Les hooks permanents continuent les nouvelles tentatives indéfiniment à des intervalles de 60 secondes (configurable via permanentIntervalReset).

Types d’événements

Événements de réunion

Événements utilisateur

Événements de chat et de notes

Événements de sondage

Événements Enregistrement et Lecture (RAP)

Configuration du serveur

Les options suivantes peuvent être configurées dans /etc/bigbluebutton/bbb-webhooks.yml ou config/default.yml. La plupart de ces options ne sont pas couvertes par la documentation officielle. undocumented

Notes opérationnelles

• Persistance : Les hooks sont stockés dans Redis et survivent aux redémarrages du serveur (resynchronisés au démarrage).
• Ordonnancement : Les callbacks sont envoyés séquentiellement pour chaque hook, un à la fois, en préservant l’ordre des événements.
• Unicité de l’URL : La détection des doublons repose uniquement sur l’URL de callback. La même URL ne peut pas être enregistrée avec des filtres meetingID ou eventID différents — le premier enregistrement l’emporte.
• Nettoyage des données : Les mappages internes des réunions sont supprimés après une semaine d’inactivité (configurable via mappings.timeout, valeur par défaut : 604800000 ms).
• Événements synthétiques : Lorsqu’une réunion se termine, des événements user-left sont automatiquement générés pour tous les utilisateurs encore connectés, car BigBlueButton lui-même n’émet pas UserLeftMeetingEvtMsg à la fin de la réunion.
• Chats privés : Seuls les messages du chat public génèrent des événements chat-group-message-sent. Les messages privés sont ignorés silencieusement.