Skip to main content
Register a new webhook endpoint that receives HTTP callbacks when events occur in your organization.

​
Endpoint

POST /v1/accounts/:accountId/webhooks

​
Authentication

Bearer token required.

​
Request Body

​
url
string
required
The URL to send webhook payloads to. Must be a valid, reachable URL.
​
events
string[]
required
List of events to subscribe to. At least one event is required.
​
roomId
string
Scope the webhook to a specific room. If omitted, the webhook fires for events in all rooms.

​
Available Events

All payloads are wrapped in a base envelope: { id, event, timestamp, ...payload }.
EventDescriptionPayload
participant.joinedA user came online in a room{ room: CollabKitRoom, user: CollabKitUser }
participant.leftA user went offline{ room: CollabKitRoom, user: CollabKitUser }
session.startedA new session started (first user joined){ room: CollabKitRoom }
session.closedA session ended (last user left){ room: CollabKitRoom, users: CollabKitUser[] }
user.createdA new user was added to a room{ room: { id }, user: CollabKitUser }
user.updatedA user’s fields changed{ room: { id }, user: CollabKitUser }
user.deletedA user was removed{ room: { id }, user: CollabKitUser }

​
Response

​
webhook
WebhookRegistration
The created webhook, including the signing secret (only returned at creation time). See WebhookRegistration.
The secret is only returned when the webhook is created. Store it securely — you cannot retrieve it later.

​
Example

curl -X POST https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/webhooks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/collab-webhook",
    "events": ["participant.joined", "participant.left"],
    "roomId": "c3003c93-60cf-4184-b85f-20be14d26dac"
  }'
Response (201)
{
  "type": "response",
  "success": true,
  "description": "Webhook created",
  "data": {
    "webhook": {
      "id": "wh_abc123",
      "organization_id": "a1b2c3d4-...",
      "url": "https://api.example.com/collab-webhook",
      "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
      "events": ["participant.joined", "participant.left"],
      "room_id": "c3003c93-60cf-4184-...",
      "enabled": true,
      "created_at": "2026-05-29T10:00:00.000Z",
      "updated_at": "2026-05-29T10:00:00.000Z"
    }
  },
  "error": null
}

​
Verifying Webhook Signatures

Each webhook delivery includes an HMAC-SHA256 signature in the headers. Verify it using the secret: 
import { createHmac } from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(body).digest('hex');
  return expected === signature;
}