Webhooks

Receive real-time event notifications from BaxCloud

Overview

Webhooks allow your application to receive real-time notifications when events happen in BaxCloud. Instead of polling for changes, BaxCloud will send HTTP POST requests to your configured endpoint whenever an event occurs.

Real-time Events

Get notified instantly when events occur

Signature Verification

Verify webhook authenticity with HMAC signatures

Automatic Retries

Failed deliveries are automatically retried

Event Types

All available webhook events

Room Events

room.created- A new room was created
room.started- A room session started
room.ended- A room session ended
room.deleted- A room was deleted

Participant Events

participant.joined- A participant joined a room
participant.left- A participant left a room
participant.updated- Participant details were updated

Recording Events

recording.started- Recording started
recording.stopped- Recording stopped
recording.available- Recording is ready for download

Stream Events

stream.started- Live stream started
stream.ended- Live stream ended

Setup Webhooks

Configure webhook endpoints in your project

Step 1: Create Webhook Endpoint

Navigate to your project settings and add a webhook endpoint URL:

1https://your-app.com/webhooks/baxcloud

Step 2: Select Events

Choose which events you want to receive notifications for. You can select specific events or subscribe to all events.

Step 3: Get Signing Secret

After creating the webhook, you'll receive a signing secret. Store this securely - you'll need it to verify webhook authenticity.

1whsec_abc123xyz789...

Webhook Payload

Structure of incoming webhook requests

BaxCloud sends webhooks as HTTP POST requests with a JSON payload:

1{
2  "id": "evt_abc123xyz",
3  "type": "room.created",
4  "created": 1705576800,
5  "data": {
6    "object": {
7      "id": "room_abc123xyz",
8      "name": "my-room",
9      "liveType": "video_call",
10      "status": "active",
11      "createdAt": "2026-01-18T10:00:00Z",
12      "metadata": {}
13    }
14  }
15}

Example: participant.joined

1{
2  "id": "evt_def456uvw",
3  "type": "participant.joined",
4  "created": 1705576860,
5  "data": {
6    "object": {
7      "id": "part_xyz789abc",
8      "userId": "user-123",
9      "name": "John Doe",
10      "roomId": "room_abc123xyz",
11      "isHost": false,
12      "joinedAt": "2026-01-18T10:01:00Z"
13    }
14  }
15}

Signature Verification

Verify webhook authenticity to prevent spoofing

BaxCloud signs all webhook requests with HMAC-SHA256. Verify the signature to ensure the webhook came from BaxCloud and wasn't tampered with.

server.js
1import crypto from 'crypto';
2
3function verifyWebhook(payload, signature, secret) {
4  const expectedSignature = crypto
5    .createHmac('sha256', secret)
6    .update(payload)
7    .digest('hex');
8
9  return crypto.timingSafeEqual(
10    Buffer.from(signature),
11    Buffer.from(expectedSignature)
12  );
13}
14
15// Express.js example
16app.post('/webhooks/baxcloud', express.raw({ type: 'application/json' }), (req, res) => {
17  const signature = req.headers['x-baxcloud-signature'];
18  const payload = req.body.toString();
19
20  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
21    return res.status(401).send('Invalid signature');
22  }
23
24  const event = JSON.parse(payload);
25  
26  // Handle the event
27  switch (event.type) {
28    case 'room.created':
29      // Handle room created
30      break;
31    case 'participant.joined':
32      // Handle participant joined
33      break;
34    // ... handle other events
35  }
36
37  res.status(200).send('OK');
38});

Always verify signatures

Verifying webhook signatures is critical for security. Never process unverified webhooks.

Best Practices

Return 200 OK quickly

Process webhooks asynchronously and return 200 OK immediately

Handle duplicate events

Use event IDs to detect and ignore duplicate deliveries

Verify signatures first

Always verify the webhook signature before processing the payload

Use HTTPS endpoints

Webhook URLs must use HTTPS for security

Monitor webhook health

Check the webhook logs in your dashboard for delivery failures

Retry Logic

If your endpoint returns a non-200 status code or times out, BaxCloud will automatically retry the webhook delivery with exponential backoff:

11st retry: after 5 seconds
22nd retry: after 30 seconds
33rd retry: after 2 minutes
44th retry: after 10 minutes
55th retry: after 30 minutes

After 5 failed attempts, the webhook delivery is marked as failed and you'll be notified via email. You can manually retry failed webhooks from the dashboard.

Next Steps

Authentication

Learn about API authentication and security

Rooms API

Manage rooms programmatically

View Examples

See webhook implementation examples