Webhooks

Webhooks deliver real-time HTTP notifications when events occur in your workspace.

Events

Event	Description
room.created	A room was created in the workspace
room.joined	A participant joined a room
room.left	A participant left a room
recording.started	Recording started in a room
recording.completed	Recording finished and is available
member.joined	A new member joined the workspace
member.left	A member left or was removed

---

Webhook Payload

Each webhook delivery sends a JSON POST request:

{
  "event": "room.created",
  "timestamp": "2024-03-10T12:00:00.000Z",
  "data": {
    "room_name": "team-standup",
    "room_id": 1,
    "created_by": "John Doe"
  }
}

Headers

Header	Description
X-Webhook-Event	Event type (e.g., room.created)
X-Webhook-Timestamp	ISO 8601 timestamp
X-Webhook-Signature	HMAC-SHA256 signature of the payload
Content-Type	application/json

---

Verifying Signatures

Each webhook has a signing secret (prefixed whsec_). To verify a delivery:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

---

List Webhooks

GET /api/workspaces/:id/webhooks

---

List Available Events

GET /api/workspaces/:id/webhooks/events

Response:

{
  "events": [
    "room.created",
    "room.joined",
    "room.left",
    "recording.started",
    "recording.completed",
    "member.joined",
    "member.left"
  ]
}

---

Create Webhook

Owner or admin only.

POST /api/workspaces/:id/webhooks

Request body:

Field	Type	Required	Description
name	string	Yes	Webhook name
url	string	Yes	Endpoint URL
events	string[]	Yes	Events to subscribe to

Response:

{
  "webhook": {
    "id": 1,
    "name": "Slack notifications",
    "url": "https://hooks.slack.com/...",
    "secret": "whsec_...",
    "events": "[\"room.created\",\"recording.completed\"]",
    "is_active": 1,
    ...
  }
}

---

Update Webhook

PATCH /api/workspaces/:id/webhooks/:webhookId

Request body:

Field	Type	Description
toggle	boolean	Toggle active/inactive
name	string	New name
url	string	New endpoint URL
events	string[]	New event subscriptions

---

Delete Webhook

DELETE /api/workspaces/:id/webhooks/:webhookId

---

Delivery History

View recent webhook deliveries.

GET /api/workspaces/:id/webhooks/:webhookId/deliveries

Response:

{
  "deliveries": [
    {
      "id": 1,
      "webhook_id": 1,
      "event": "room.created",
      "payload": "{...}",
      "response_status": 200,
      "response_body": "ok",
      "success": 1,
      "created_at": 1710000000
    }
  ]
}