Webhooks & Workflows

This guide covers setting up webhooks for external notifications and workflows for running custom code when events occur in your rooms.

Webhooks vs Workflows

Feature	Webhooks	Workflows
What	HTTP POST to your server	Custom JS/TS code executed in Cloudflare Workers
Where	Your own infrastructure	CollabKit’s infrastructure
Use case	Notify external services, update databases	Process events, transform data, trigger side effects
Setup	Provide a URL	Provide source code
Auth	HMAC-SHA256 signature verification	N/A (runs in a secure sandbox)

Part 1: Webhooks

Create a Webhook

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", "user.created"]
  }'

Save the secret from the response — you need it to verify webhook signatures.

Available Events

Event	When It Fires
`participant.joined`	A user comes online in a room
`participant.left`	A user goes offline
`session.started`	First user joins a room (new session)
`session.closed`	Last user leaves a room (session ends)
`user.created`	A new user is added to a room via `POST /users`
`user.updated`	A user’s fields are changed
`user.deleted`	A user is removed from a room

Webhook Payload

Each delivery sends a POST request with a JSON body:

{
  "event": "participant.joined",
  "data": {
    "userId": "user-001",
    "roomId": "c3003c93-60cf-4184-..."
  },
  "timestamp": "2026-05-29T10:06:00.000Z"
}

Verify Webhook Signatures

Each delivery includes an HMAC-SHA256 signature. Verify it to ensure the payload is authentic:

import { createHmac, timingSafeEqual } from 'crypto';

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

  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler (Express example)
app.post('/collab-webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body);

  if (!verifyWebhookSignature(body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { event, data } = req.body;
  switch (event) {
    case 'participant.joined':
      console.log(`User ${data.userId} joined room ${data.roomId}`);
      break;
    case 'session.closed':
      console.log(`Session ended in room ${data.roomId}`);
      break;
  }

  res.status(200).send('OK');
});

Scope to a Room

Limit webhooks to a specific room:

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/room-webhook",
    "events": ["participant.joined"],
    "roomId": "c3003c93-60cf-4184-b85f-20be14d26dac"
  }'

Monitor Deliveries

Check the delivery log to debug issues:

curl "https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/webhooks/wh_abc123/deliveries?limit=10" \
  -H "Authorization: Bearer ${TOKEN}"

Each delivery shows the status (pending, success, failed), HTTP status code, attempt count, and next retry time.

Part 2: Workflows

Workflows let you run custom JavaScript in response to events, directly on CollabKit’s infrastructure.

Create a Workflow

curl -X POST https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/workflows \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Log new participants",
    "events": ["participant.joined", "participant.left"],
    "code": "export default async function(event, { room }) {\n  const roomData = await room.get();\n  console.log(`[${event.event}] User ${event.data.userId} in room ${roomData.name}`);\n  return { logged: true };\n}"
  }'

Workflow Bindings

Your workflow code receives the event and a set of bindings:

export default async function(event, bindings) {
  // event.event    -- "participant.joined", etc.
  // event.data     -- event-specific payload

  const { store, room, files } = bindings;

  // Read from KV stores
  const value = await store.get('tasks', 'task-1');
  const all = await store.getAll('tasks');

  // Read room and user data
  const roomData = await room.get();
  const users = await room.getUsers();

  // Work with files
  const fileList = await files.list();

  return { success: true };
}

Binding	Methods	Description
`store`	`get(store, key)`, `getAll(store)`	Read-only KV store access
`room`	`get()`, `getUsers()`	Read-only room and user metadata
`files`	`list()`	Scoped R2 file listing
`event`	(passed as first arg)	The triggering event data

Example: Notify Slack on Session Start

export default async function(event, { room }) {
  if (event.event !== 'session.started') return;

  const roomData = await room.get();

  await fetch('https://hooks.slack.com/services/YOUR/WEBHOOK/URL', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `Collaboration session started in "${roomData.name}"`,
    }),
  });

  return { notified: true };
}

Example: Auto-Create Welcome Store Entry

export default async function(event, { store }) {
  if (event.event !== 'user.created') return;

  // Note: workflow store access is read-only
  // Use this to check existing state, then use fetch()
  // to call external APIs with the data
  const existing = await store.get('settings', event.data.userId);
  console.log('User settings:', existing);

  return { checked: true };
}

Monitor Executions

Check the execution log:

curl "https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/workflows/wf_abc123/executions?limit=10" \
  -H "Authorization: Bearer ${TOKEN}"

Each execution shows status, duration, and the result or error message.

Enable/Disable Workflows

# Disable
curl -X PATCH https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/workflows/wf_abc123 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Re-enable
curl -X PATCH https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/workflows/wf_abc123 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Next Steps

Combine webhooks with workflows for a complete event pipeline
Use the dashboard to manage webhooks and workflows visually
Review the Webhook API reference and Workflow API reference for full details

​Webhooks vs Workflows

​Part 1: Webhooks

​Create a Webhook

​Available Events

​Webhook Payload

​Verify Webhook Signatures

​Scope to a Room

​Monitor Deliveries

​Part 2: Workflows

​Create a Workflow

​Workflow Bindings

​Example: Notify Slack on Session Start

​Example: Auto-Create Welcome Store Entry

​Monitor Executions

​Enable/Disable Workflows

​Next Steps