Create Webhook

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 }.

Event	Description	Payload
`participant.joined`	A user came online in a room	`{ room:` `CollabKitRoom, user:` `CollabKitUser` `}`
`participant.left`	A user went offline	`{ room:` `CollabKitRoom, user:` `CollabKitUser` `}`
`session.started`	A new session started (first user joined)	`{ room:` `CollabKitRoom` `}`
`session.closed`	A session ended (last user left)	`{ room:` `CollabKitRoom, users:` `CollabKitUser[] }`
`user.created`	A new user was added to a room	`{ room: { id }, user:` `CollabKitUser` `}`
`user.updated`	A user’s fields changed	`{ room: { id }, user:` `CollabKitUser` `}`
`user.deleted`	A 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"
  }'

const res = await fetch(`https://api.collab-kit.com/v1/accounts/${accountId}/webhooks`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://api.example.com/collab-webhook',
    events: ['participant.joined', 'participant.left'],
  }),
});
const { data } = await res.json();
// SAVE data.webhook.secret securely!

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;
}

Overview

Rooms

Users

Storage

Webhooks

Workflows

Endpoint

Authentication

Request Body

Available Events

Response

Example

Verifying Webhook Signatures

​Endpoint

​Authentication

​Request Body

​Available Events

​Response

​Example

​Verifying Webhook Signatures

Endpoint

Authentication

Request Body

Available Events

Response

Example

Verifying Webhook Signatures