Comment on page
Tracking room events with Webhooks
With Webhooks you can set up user-defined callbacks triggered by meeting events. These are a great way to programmatically keep track of some of the events and actions happening around your meetings.
Webhooks are managed from the "Configure" section of your account, so they need to be set up by an admin in your organization.

Visit the "Configure" section of your Whereby Embedded account dashboard and scroll down to find the Webhooks setup.
At the moment the following event types are supported:
room.client.joined
- this is sent when a user joins the meeting roomroom.client.left
- this is sent when a user leaves the meeting room (this could be via the leave button or by closing the browser tab)room.client.knocked
- this is sent when a visitor knocks the meeting room from the waiting roomroom.client.knockCancelled
- this is sent when a visitor cancels their knock from the waiting room (this could be via the cancel button or a result of network issues)room.session.started
: Sent when a room session starts, which is when there are at least 2 users in a room.room.session.ended
: Sent when a room session ends. Currently, a session will end when the number of participants has been less than 2 for some time. This heuristic could change in the future to better determine that a session has ended.transcription.finished
: Sent when a transcription has finished processing.transcription.failed
: Sent when a transcription has failed to process.recording.finished
: Sent when a cloud recording has finished and the recording has uploaded successfully.
Events are delivered to their corresponding webhook endpoint in JSON format, as the body of an HTTP request. The table below describes their top-level attributes.
Property | Description |
---|---|
id | String that uniquely identifies the event. |
apiVersion | The Whereby API version used to populate data. Refer to the details on Versioning for how webhook data may change. |
createdAt | ISO representation of the creation date of the event. |
type | The event’s type identifier, e.g. room.client.joined |
data | Object containing information associated with the event. |
Please note that in-room webhook events are sent for interactions that happen between the creation of the room and an hour after the
endDate
of a room. Also consider that a particular event can be sent more than once, and that you could receive events in non-chronological order.Properties in
data
that are common to all in-room webhook events:Property | Description |
---|---|
meetingId | The identifier of the meeting that the user has joined/left or where the session has started/ended. |
roomName | The string that identifies the room assigned to the meeting. It’s the last path parameter of the roomUrl. |
Additional properties in
data
for room.client.joined
, room.client.left room.client.knocked
and room.client.knockCancelled
:Property | Description |
---|---|
displayName | The visible name displayed to others in the meeting. |
Additional properties in data for just
room.client.joined
and room.client.left
:Property | Description |
---|---|
roleName | The client’s role depending on what URL they use to access the meeting. |
numClients | Number of clients connected to the meeting after the event. |
numClientsByRoleName | Number of clients connected to the meeting after the event, grouped by the roleName. |
The property
roleName
will have one of the following values:owner
: A user with an admin account in your Embedded organization.member
: A user with an account in your Embedded organization.host
: A user joined using thehostRoomUrl
.visitor
: A user joined using the regularroomUrl
.granted_visitor
: TheroleName
that is assigned to a Participant after they have knocked and been let in by a Host.viewer
: A user joined using theviewerRoomUrl
.granted_viewer
: TheroleName
that is assigned to a Participant if they are queued before a Host joins.recorder
: A cloud recording instance has started or stopped.streamer
: A streaming instance has started or stopped.
An example of a webhook event object:
JSON
{
"id": "d7c4df48b85318352b47d2df45872bf9be87595af379e2a8ad8f1ad28b2a482e",
"apiVersion": "1.0",
"createdAt": "2021-01-21T16:29:59.681Z",
"type": "room.client.joined",
"data": {
"roleName": "host",
"displayName": "Joe Bloggs",
"meetingId": "134",
"roomName": "/af0b7b66-c738-4981-887a-ad416754f32d",
"numClients": 8,
"numClientsByRoleName": {
"host": 1,
"visitor": 7
},
"metadata": "<custom-metadata>",
"externalId": "<custom-id>"
}
}
Whereby transcriptions are currently in Beta and available to selected customers only. Email us at [email protected] to join our pilot program (terms and conditions apply).
Properties in
data
that are common to all transcription webhook events:Property | Description |
---|---|
transcriptionId | The identifier of the transcription that has finished processing or failed to process. |
Additional properties in data for just
transcription.finished
:Property | Description |
---|---|
recordingId | The identifier of the recording that the transcription is associated with. |
durationInSeconds | The duration of the recording in seconds. |
Additional properties in data for just
transcription.failed
:Property | Description |
---|---|
error | The error message that describes why the transcription failed to process. |
Properties in
data
for the recording.finished
webhook event:Property | Description |
---|---|
filename | The name and extension of the recording. |
recordingId | The identifier of the recording. |
status | The final status of the recording. It can be only completed for now. |
To prevent from man-in-the-middle attacks ↗ , webhook requests to your endpoint contain a signature in the
Whereby-Signature
header. This string is generated with a unique secret that only you can view when creating or editing a webhook in the Embedded dashboard. Only Whereby and you have access to this secret, and no third party can send forged events to your endpoint. On top of that the header also includes a timestamp to help you prevent replay attacks. The header is composed of a timestamp and the signature itself, for example:Text
Whereby-Signature:
t=1606227791,v1=94a23dc9d73e8e6abdf9d4095aee954697e9317e9649e742361b35707edd45a3
To verify an event’s signature, follow these steps:
- 1.Extract the timestamp and signature by splitting the string on
,
then removing botht=
andv1=
from the resulting strings. - 2.Prepare the
signedPayload
string by concatenating the timestamp (as a string), the character.
and the JSON event object (the request body). - 3.Calculate the HMAC: It is the SHA256 hash of
signedPayload
, using the endpoint’s signing secret (the one you get when creating the webhook) as the key. - 4.Compare the signature from the header to the one you just generated. To protect yourself from timing attacks consider using a constant-time equality function instead of the default equality operator of the language you’re using. Finally, to prevent replay attacks, compare the header’s timestamp with the current one and decide if the elapsed time is within your allowed threshold.
An example of a webhook event validation:
Node
import crypto from "crypto";
const WEBHOOK_SECRET = "<WEBHOOK_SECRET>";
const MAX_ELAPSED_TIME = 1000 * 60; // 1 minutes in milliseconds
function isWebhookEventValid({ body, headers }) {
const wbSignature = headers["whereby-signature"];
const matches = wbSignature.matchAll(/t=(.*),v1=(.*)/gm);
let timestamp, signature;
for (const match of matches) {
timestamp = match[1];
signature = match[2];
}
const current = new Date();
const diffTime = current - parseInt(timestamp * 1000, 10);
const signedPayload = timestamp + "." + JSON.stringify(body);
const sha256Hasher = crypto.createHmac("sha256", WEBHOOK_SECRET);
const hash = sha256Hasher.update(signedPayload);
const hashStr = hash.digest("hex");
return (
crypto.timingSafeEqual(
Buffer.from(hashStr, "utf-8"),
Buffer.from(signature, "utf-8")
) && diffTime < Whereby.MAX_ELAPSED_TIME
);
}
Any
5xx
response to the webhook delivery request will trigger a retry, for a total of 2 retries. A short exponential backoff will be used. We also have a 5 seconds timeout on webhook requests, if the response takes longer than that the same retry mechanism will be used.Last modified 30d ago