Webhooks – Eventos en tiempo real

Los webhooks de BigBlueButton permiten que tu aplicación reciba notificaciones HTTP POST en tiempo real cada vez que ocurren eventos de reunión. En lugar de consultar repetidamente getMeetings o getMeetingInfo, registras una URL de devolución de llamada y BigBlueButton te envía automáticamente los eventos. Este capítulo cubre los tres endpoints API de webhook, el formato de callback, los tipos de eventos, el comportamiento de reintento y la configuración del servidor.

Requisitos previos

El paquete bbb-webhooks debe instalarse en el servidor BigBlueButton antes de que los endpoints de webhook estén disponibles:

sudo apt-get install bbb-webhooks

hooks/create — Registrar un webhook

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

Respuesta exitosa

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

Registro duplicado

Si se registra de nuevo la misma callbackURL, la respuesta sigue devolviendo SUCCESS pero incluye un duplicateWarning. El hook existente se mantiene sin cambios — meetingID, eventID y getRaw no se actualizan.

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

Respuestas de error

hooks/list — Listar webhooks registrados

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

Respuesta exitosa

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

Respuestas de error

hooks/destroy — Eliminar un webhook

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

Respuesta exitosa

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

Respuestas de error

hooks/ping — Comprobación de estado

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

Este endpoint de diagnóstico no requiere suma de verificación. Si la aplicación webhook es accesible, devuelve la cadena de texto sin formato bbb-webhooks API up! (no XML, tipo de contenido text/plain). undocumented

Formato de callback

Los callbacks de webhook se envían como solicitudes HTTP POST con tipo de contenido application/x-www-form-urlencoded. El cuerpo de la solicitud contiene tres campos:

Cuerpo de callback procesado (getRaw=false)

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

Cuerpo de callback sin procesar (getRaw=true)

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

Validación de la suma de verificación del callback

En el modo predeterminado, cada URL de callback recibe un parámetro de consulta checksum que tu aplicación debe verificar:

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

La fórmula de validación es:

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

Modo Auth 2.0 / Bearer

Como alternativa, el servidor puede configurarse con auth2_0: true. En este modo, no se añade ningún parámetro checksum a la URL de callback. En su lugar, el secreto compartido se envía como un token Bearer en la cabecera Authorization: undocumented

Authorization: Bearer <shared-secret>

Comportamiento del callback

• Códigos de estado HTTP aceptados: HTTP 2xx y HTTP 401 se consideran una entrega correcta. Todos los demás códigos de estado activan un reintento. undocumented
• Redirecciones: Se siguen las respuestas HTTP 3xx (hasta 10 saltos). Solo si no se alcanza ningún 2xx/401 después de 10 redirecciones, el callback se considera fallido.
• Tiempo de espera: Cada solicitud de callback tiene un tiempo de espera de 5 segundos (configurable mediante requestTimeout).
• Intervalos de reintento: En caso de fallo, los reintentos usan back-off exponencial: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 intentos durante aproximadamente 5 minutos, configurable mediante retryIntervals).
• Después de agotar todos los reintentos: Los hooks no permanentes se eliminan automáticamente. Los hooks permanentes siguen reintentándolo indefinidamente a intervalos de 60 segundos (configurable mediante permanentIntervalReset).

Tipos de eventos

Eventos de reunión

Eventos de usuario

Eventos de chat y notas

Eventos de encuesta

Eventos de grabación y reproducción (RAP)

Configuración del servidor

Las siguientes opciones se pueden configurar en /etc/bigbluebutton/bbb-webhooks.yml o config/default.yml. La mayoría de estas opciones no están cubiertas en la documentación oficial. undocumented

Notas operativas

• Persistencia: Los hooks se almacenan en Redis y sobreviven a reinicios del servidor (se resincronizan al arrancar).
• Orden: Las callbacks se envían secuencialmente por hook, una a la vez, preservando el orden de los eventos.
• Unicidad de URL: La detección de duplicados se basa únicamente en la URL de callback. La misma URL no puede registrarse con filtros meetingID o eventID diferentes; prevalece el primer registro.
• Limpieza de datos: Los mapeos internos de reuniones se eliminan después de una semana de inactividad (configurable mediante mappings.timeout, por defecto: 604800000 ms).
• Eventos sintéticos: Cuando termina una reunión, se generan automáticamente eventos user-left para todos los usuarios aún conectados, porque BigBlueButton en sí no emite UserLeftMeetingEvtMsg al finalizar una reunión.
• Chats privados: Solo los mensajes del chat público generan eventos chat-group-message-sent. Los mensajes privados se ignoran silenciosamente.