Webhooks – Real-Time Events

BigBlueButton Webhooks let your application receive real-time HTTP POST notifications whenever meeting events occur. Instead of repeatedly polling getMeetings or getMeetingInfo, you register a callback URL and BigBlueButton pushes events to you automatically. This chapter covers the three webhook API endpoints, the callback format, event types, retry behaviour, and server configuration.

Prerequisites

The bbb-webhooks package must be installed on the BigBlueButton server before webhook endpoints become available:

sudo apt-get install bbb-webhooks

hooks/create — Register a Webhook

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

Successful Response

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

Duplicate Registration

If the same callbackURL is registered again, the response still returns SUCCESS but includes a duplicateWarning. The existing hook is kept unchanged — meetingID, eventID, and getRaw are not updated.

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

Error Responses

hooks/list — List Registered Webhooks

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

Successful Response

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

Error Responses

hooks/destroy — Remove a Webhook

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

Successful Response

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

Error Responses

hooks/ping — Health Check

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

This diagnostic endpoint requires no checksum. If the webhook application is reachable it returns the plain-text string bbb-webhooks API up! (not XML, content type text/plain). undocumented

Callback Format

Webhook callbacks are sent as HTTP POST requests with content type application/x-www-form-urlencoded. The request body contains three fields:

Processed Callback Body (getRaw=false)

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

Raw Callback Body (getRaw=true)

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

Callback Checksum Validation

In the default mode, each callback URL receives a checksum query parameter that your application should verify:

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

The validation formula is:

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

Auth 2.0 / Bearer Mode

Alternatively, the server can be configured with auth2_0: true. In this mode, no checksum parameter is appended to the callback URL. Instead, the shared secret is sent as a Bearer token in the Authorization header: undocumented

Authorization: Bearer <shared-secret>

Callback Behaviour

• Accepted HTTP status codes: HTTP 2xx and HTTP 401 are treated as successful delivery. All other status codes trigger a retry. undocumented
• Redirects: HTTP 3xx responses are followed (up to 10 hops). Only if no 2xx/401 is reached after 10 redirects does the callback count as failed.
• Timeout: Each callback request has a timeout of 5 seconds (configurable via requestTimeout).
• Retry intervals: On failure, retries use exponential back-off: 100ms, 500ms, 1s, 2s, 4s, 8s, 10s, 30s, 60s, 60s, 60s, 60s (12 attempts over approximately 5 minutes, configurable via retryIntervals).
• After all retries are exhausted: Non-permanent hooks are automatically removed. Permanent hooks continue retrying indefinitely at 60-second intervals (configurable via permanentIntervalReset).

Event Types

Meeting Events

User Events

Chat and Notes Events

Poll Events

Record and Playback (RAP) Events

Server Configuration

The following options can be configured in /etc/bigbluebutton/bbb-webhooks.yml or config/default.yml. Most of these options are not covered in the official documentation. undocumented

Operational Notes

• Persistence: Hooks are stored in Redis and survive server restarts (re-synced on startup).
• Ordering: Callbacks are sent sequentially per hook, one at a time, preserving event order.
• URL uniqueness: Duplicate detection is based solely on the callback URL. The same URL cannot be registered with different meetingID or eventID filters — the first registration wins.
• Data cleanup: Internal meeting mappings are removed after one week of inactivity (configurable via mappings.timeout, default: 604800000 ms).
• Synthetic events: When a meeting ends, user-left events are automatically generated for all still-connected users, because BigBlueButton itself does not emit UserLeftMeetingEvtMsg at meeting end.
• Private chats: Only public chat messages generate chat-group-message-sent events. Private messages are silently ignored.