> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Workflows

> Automate server-side actions in response to collaboration events.

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

Register a URL to receive HTTP callbacks when events occur:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```typescript theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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:

```bash theme={null}
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

```bash theme={null}
# 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](https://dash.collab-kit.com) to manage webhooks and workflows visually
* Review the [Webhook API reference](/api-reference/webhooks/create-webhook) and [Workflow API reference](/api-reference/workflows/create-workflow) for full details