BigBlueButton webhooks – Complete Guide – create hooks

BigBlueButton have a application which is not the part of core BBB but we can separately install it, Bigbluebutton webhooks is a NodeJS application which listen to all the available BBB events and send post request to any other registered hooks, if we have created any. And we can use this hooks to receive the events that we need and store the data we receive.

A webhook allow any application to subscribe to their events and whenever this event will happen these subscriber will get notified and same approach happens in bigbluebutton webhook. Bigbluebutton also have many different type of event and an application can subscribe to all event or any of the specified event and in the response app will receive the data of that particular event when it happens

Installation

To install webhooks, you need to run the below command on your BigBlueButton server:

$ sudo apt-get install bbb-webhooks

Otherwise you can install bigbluebutton webhooks from github repository But i would recommend to go with above simple step instead of manually install and configure it.

after installation of webhooks you will have 3 new apis these apis are below listed

• create hook
• destroy hook
• list all hooks

Later we will discuss about these APIs in details

Create Hook – Hooks/Create

To create a new hook we call this api with the end point hooks/create. We can call this api multiple times with same parameters as it will not create new hook if already created. Adding optional parameters like meetingID will subscribe and valid only for that meeting ID and same for EventID which allow to subscribe only for that particular eventID.

Make sure these hooks are created permanently until these hooks are not removed or this callback url fails to send back the 200 response.

Parameteres

Required : callbackURL

Optional: meetingID, eventID, getRaw

Example -> http://mybbb.com/bigbluebutton/api/hooks/create?[parameters]&checksum=[checksum]

Response of hook successfully created, here hook id could be different

<response>
  <returncode>SUCCESS</returncode>
  <hookID>2</hookID>
  <permanentHook>false</permanentHook>
  <rawData>false</rawData>
</response>

Add Permanent Hook – Bigbluebutton Webhooks:

If you want all webhooks from a BBB server to post to your 3rd party application/s, you can modify the configuration file to include permanentURLs and define one or more server urls which you would like the webhooks to post back to.

These types of hooks will never be removed automatically unlike the above. To add permanent URL you need to make sure you have a permanent callback URL and you have to modify the config file of bbb-webhooks application , everything except adding callback URL manually to the file will be same like it will have all the events and will have the same types of the data. Also make sure that for permanent URL you never need to call APIs like create or destroy

To add these permanent urls, we need to do below steps:

• cd /usr/local/bigbluebutton/bbb-webhooks
• sudo vim config/default.yml
• Find hooks.permanentURLs in your config/default.yml and modify it as below:

hooks:
   permanentURLs: 
      - url: 'https://appapi.abc.com/meeting/webhook-route',
        getRaw: false
      - url: 'https://adminapi.bcd.com/meeting/webhook-route',
        getRaw: false

After Adding these permanentUrls in the config file to take effect on the server we need to restart the bbb-webhooks service on bbb server as below

sudo service bbb-webhooks restart

still you may not see these permanent webhooks url in working , it is because we have to flush the redis database take these entries in effect. use the below command to pick the latest added callback urls in redis database

• redis-cli flushall
• IMPORTANT: Running the above command clears the redis database entirely. This will result in all meetings, processing or not, to be cleared from the database, and may result in broken meetings currently processing.

Webhook Event List:

• MeetingCreatedEvtMsg,
• MeetingDestroyedEvtMsg,
• ScreenshareRtmpBroadcastStartedEvtMsg,
• ScreenshareRtmpBroadcastStoppedEvtMsg,
• SetCurrentPresentationEvtMsg,
• RecordingStatusChangedEvtMsg,
• UserJoinedMeetingEvtMsg,
• UserLeftMeetingEvtMsg,
• UserJoinedVoiceConfToClientEvtMsg,
• UserLeftVoiceConfToClientEvtMsg,
• PresenterAssignedEvtMsg,
• PresenterUnassignedEvtMsg,
• UserBroadcastCamStartedEvtMsg,
• UserBroadcastCamStoppedEvtMsg,
• UserEmojiChangedEvtMsg,
• GroupChatMessageBroadcastEvtMsg,
• PublishedRecordingSysMsg,
• UnpublishedRecordingSysMsg,
• DeletedRecordingSysMsg,
• meeting_created_message,
• meeting_destroyed_event,
• user_joined_message,
• user_left_message,
• user_listening_only,
• user_joined_voice_message,
• user_left_voice_message,
• user_shared_webcam_message,
• user_unshared_webcam_message,
• user_status_changed_message,
• archive_started,
• archive_ended,
• sanity_started,
• sanity_ended,
• post_archive_started,
• post_archive_ended,
• process_started,
• process_ended,
• post_process_started,
• post_process_ended,
• publish_started,
• publish_ended,
• post_publish_started,
• post_publish_ended,
• published,
• unpublished,
• deleted,
• PadContentEvtMsg

Destroy Hook – Hooks/Destroy

We can remove hooks and unsubscribe the events, To remove a previously created hook we call this hook/destroy endpoint and which have hookID as required parameter

Parameters :

Required: hookID

Example -> http://mybbb.com/bigbluebutton/api/hooks/destroy?[parameters]&checksum=[checksum]

List All Hook – Hooks/List

To check all available or created hooks we use this endpoint hooks/list . This api has only one parameter meetingID which is optional. And in case meetingID parameter is not provided it will return all registered hooks to this BBB server

Parameters :

Optional: meetingID

Example -> http://mybbb.com/bigbluebutton/api/hooks/list?[parameters]&checksum=[checksum]

Example Response of hooks/list

<response>
  <returncode>SUCCESS</returncode>
  <hooks>
    <hook>
      <hookID>1</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/789789yiuyi]]></callbackURL>
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
    <hook>
      <hookID>2</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/iyuyrit111111]]></callbackURL>
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
  </hooks>
</response>

More to include

If you need any help in bigbluebutton webhooks installation or setup and configuration you can hire an expert. We are top most expert in bigbluebutton development, customization, enhancement and maintaining it.

Important Notes

Webhook Callback format:

Webhook Testing

Webhook Development

Add new Webhook Events