BigBlueButton/bigbluebutton-Github
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #19401 from prlanzarin/u30/build/webhooks-v3

Browse Source 
build(bbb-webhooks): v3.0.0-beta.3
This commit is contained in:
Anton Georgiev 2024-01-09 15:35:00 -05:00 committed by GitHub
commit a823dd5a74
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 24 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
bbb-webhooks.placeholder.sh
View File

@ -1 +1 @@
git clone --branch v2.6.1 --depth 1 https://github.com/bigbluebutton/bbb-webhooks bbb-webhooks
git clone --branch v3.0.0-beta.3 --depth 1 https://github.com/bigbluebutton/bbb-webhooks bbb-webhooks

6
build/packages-template/bbb-webhooks/after-install.sh
View File

@ -10,13 +10,13 @@ case "$1" in
chown bigbluebutton:bigbluebutton $TARGET
BBB_HOST=$(bbb-conf --secret | grep -F URL: | sed 's#^.*://##; s#/.*##')
BBB_SECRET=$(bbb-conf --secret | grep -F Secret: | sed 's/.*Secret: //')
BBB_SECRET=$(bbb-conf --secret | grep -F Secret: | sed 's/.*Secret: //')
yq e -i ".bbb.sharedSecret = \"$BBB_SECRET\"" $TARGET
yq e -i ".bbb.serverDomain = \"$BBB_HOST\"" $TARGET
yq e -i '.bbb.auth2_0 = true' $TARGET
yq e -i '.server.port = 3005' $TARGET
yq e -i '.hooks.getRaw = false' $TARGET
yq e -i '.modules."../out/webhooks/index.js".config.getRaw = false' $TARGET
yq e -i '.log.filename = "/var/log/bbb-webhooks/bbb-webhooks.log"' $TARGET
mkdir -p /var/log/bbb-webhooks/
touch /var/log/bbb-webhooks/bbb-webhooks.log

4
build/packages-template/bbb-webhooks/build.sh
View File

@ -22,11 +22,11 @@ done
mkdir -p staging/usr/local/bigbluebutton/bbb-webhooks
find -maxdepth 1 ! -path . ! -name staging $(printf "! -name %s " $(cat .build-files)) -exec cp -r {} staging/usr/local/bigbluebutton/bbb-webhooks/ \;
find -maxdepth 1 ! -path . ! -name staging ! -name .git $(printf "! -name %s " $(cat .build-files)) -exec cp -r {} staging/usr/local/bigbluebutton/bbb-webhooks/ \;
pushd .
cd staging/usr/local/bigbluebutton/bbb-webhooks/
npm install --unsafe-perm --production
npm ci --omit=dev
popd
cp webhooks.nginx staging/usr/share/bigbluebutton/nginx/webhooks.nginx

39
docs/docs/development/webhooks.md
View File

@ -15,7 +15,7 @@ receive HTTP POST requests.
These web hooks allow 3rd party applications to subscribe to different events that happen during a
BigBlueButton session. An event can be: a meeting was created, a user joined, a new presentation was
uploaded, a user left, a recording is being processed, and many others. You can see the entire list
of events that generate web hooks calls in [this file](https://github.com/bigbluebutton/bbb-webhooks/blob/develop/messageMapping.js).
of events that generate web hooks calls in [this file](https://github.com/bigbluebutton/bbb-webhooks/blob/fea98d5969050cec792b2a5890f58fd91ce57872/src/process/event.js#L8-L54).
## Installation
@ -59,7 +59,7 @@ Hooks are permanently stored on redis and will enabled until the hook is explici
```xml
<response>
<returncode>SUCCESS</returncode>
<hookID>1</hookID>
<hookID>12345678-1234-5678-1234-567812345678</hookID>
<permanentHook>false</permanentHook>
<rawData>false</rawData>
</response>
@ -70,7 +70,7 @@ Hooks are permanently stored on redis and will enabled until the hook is explici
```xml
<response>
<returncode>SUCCESS</returncode>
<hookID>1</hookID>
<hookID>12345678-1234-5678-1234-567812345678</hookID>
<messageKey>duplicateWarning</messageKey>
<message>There is already a hook for this callback URL.</message>
</response>
@ -160,14 +160,14 @@ only the global hooks, as might be expected).
<returncode>SUCCESS</returncode>
<hooks>
<hook>
<hookID>1</hookID>
<hookID>12345678-1234-5678-1234-567812345678</hookID>
<callbackURL><![CDATA[http://postcatcher.in/catchers/abcdefghijk]]></callbackURL>
<meetingID><![CDATA[my-meeting</meetingID]]>> <!-- a hook created for this meeting only -->
<permanentHook>false</permanentHook>
<rawData>false</rawData>
</hook>
<hook>
<hookID>2</hookID>
<hookID>01234567-89ab-cdef-0123-456789abcdef</hookID>
<callbackURL><![CDATA[http://postcatcher.in/catchers/1234567890]]></callbackURL>
<!-- no meetingID means this is a global hook -->
<permanentHook>false</permanentHook>
@ -226,10 +226,10 @@ request. If the registered URL is `http://my-server.com/callback`, it will recei
checksum as in `http://my-server.com/callback?checksum=yalsdk18129e019iklasd90i`.
The way the checksum is created is similar to how the checksums are calculated for
the other BigBlueButton's API calls (take a look at [`setConfigXML`](/development/api#setconfigxml)).
the other BigBlueButton's API calls.
```
sha1(<callback URL>+<data body>+<shared secret>)
sha<1|256|384|512>(<callback URL>+<data body>+<shared secret>)
```
Where:
@ -255,7 +255,7 @@ timestamp=1234567890
```
* Concatenate the original callback URL, the string from the previous step, and the BigBlueButton's salt.
* Calculate a `sha1()` of this string.
* Calculate a `sha<1|256|384|512>()` of this string.
* The checksum calculated should equal the checksum received in the parameters of the request.
## More details
@ -271,11 +271,11 @@ timestamp=1234567890
to register the hooks more than just once. You can either check if your hook is registered with
`/hooks/list` and register it if it isn't, or simply register your hook every e.g. 5 minutes.
* The application uses internal mappings to find out to which meeting the events received from redis
are related to. These mappings are removed after 24 hours of inactivity. If there are no events at
are related to. These mappings are removed after a week of inactivity. If there are no events at
all for a given meeting during this period, it will be assumed dead. This is done to prevent data
from being stored forever on redis. This means that you can have issues if you have a hook
registered for an specific meeting (doesn't happen for global hooks) and this meeting happens to
not generate events for 24 hours, but it's still valid after it. Something very, very unlikely to
not generate events for a week, but it's still valid after it. Something very, very unlikely to
happen!
* External URLs are expected to respond with the HTTP status 2xx (200 would be the default expected).
Anything different from these values will be considered an error and the callback will be called
@ -293,15 +293,15 @@ timestamp=1234567890
## Test it
The easiest way to test the web hooks application is to register hooks in your BigBlueButton server
using the [API Mate](http://mconf.github.io/api-mate/) and capture the callbacks using the
service [PostCatcher](http://postcatcher.in/).
using the [API Mate](http://mconf.github.io/api-mate/) and capture the callbacks using a 3rd party
POST catcher, such as [webhook.site](https://webhook.site/).
There's also a test server available at the bbb-webhooks source code that can be used for catching hooks,
see: https://github.com/bigbluebutton/bbb-webhooks/blob/develop/extra/interceptor.js.
Follow the steps:
* Open [PostCatcher](http://postcatcher.in/) and click on "Start testing your POST requests now"
* It will redirect you to an URL such as `http://postcatcher.in/catchers/5527e67ba4c6dd0300000738`.
Save this URL to use later.
* Open the [API Mate](http://mconf.github.io/api-mate/) and configure your server and shared secret.
* Open your webhooks catcher of choice and copy its endpoint URL.
* Open [API Mate](http://mconf.github.io/api-mate/) and configure your server and shared secret.
* On the menu "Custom parameters", there's a field "Custom API calls:". Add these values to it:
```
@ -312,18 +312,15 @@ hooks/list
* On the same menu section, add the following values to "Custom parameters:":
```
callbackURL=http://postcatcher.in/catchers/5527e67ba4c6dd0300000738
callbackURL=<your webhook catcher URL>
```
Modify this URL to the URL you got from PostCatcher earlier.
* On the API Mate, click on the "custom call: hooks/create" link. It should respond with a success
message.
* On the API Mate, click on the "custom call: hooks/list" link to check if your hook was really
registered.
* Create a meeting and join it using the API Mate.
* Do stuff inside the meeting and check your PostCatcher page, you should see events pop up on it
as you interact in your meeting.
* Do stuff inside the meeting and check your webhooks endpoint to see if it received the callbacks.
## Development