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

# Create Webhook

> Register a webhook to receive event notifications.

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

<ParamField body="url" type="string" required>
  The URL to send webhook payloads to. Must be a valid, reachable URL.
</ParamField>

<ParamField body="events" type="string[]" required>
  List of events to subscribe to. At least one event is required.
</ParamField>

<ParamField body="roomId" type="string">
  Scope the webhook to a specific room. If omitted, the webhook fires for events in all rooms.
</ParamField>

### 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`](/types/core#collabkitroom)`, user: `[`CollabKitUser`](/types/core#collabkituser)` }`    |
| `participant.left`   | A user went offline                       | `{ room: `[`CollabKitRoom`](/types/core#collabkitroom)`, user: `[`CollabKitUser`](/types/core#collabkituser)` }`    |
| `session.started`    | A new session started (first user joined) | `{ room: `[`CollabKitRoom`](/types/core#collabkitroom)` }`                                                          |
| `session.closed`     | A session ended (last user left)          | `{ room: `[`CollabKitRoom`](/types/core#collabkitroom)`, users: `[`CollabKitUser`](/types/core#collabkituser)`[] }` |
| `user.created`       | A new user was added to a room            | `{ room: { id }, user: `[`CollabKitUser`](/types/core#collabkituser)` }`                                            |
| `user.updated`       | A user's fields changed                   | `{ room: { id }, user: `[`CollabKitUser`](/types/core#collabkituser)` }`                                            |
| `user.deleted`       | A user was removed                        | `{ room: { id }, user: `[`CollabKitUser`](/types/core#collabkituser)` }`                                            |

## Response

<ResponseField name="webhook" type="WebhookRegistration">
  The created webhook, **including the signing secret** (only returned at creation time). See [`WebhookRegistration`](/types/webhooks#webhookregistration).
</ResponseField>

<Warning>
  The `secret` is only returned when the webhook is created. Store it securely -- you cannot retrieve it later.
</Warning>

## Example

<CodeGroup>
  ```bash curl 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"],
      "roomId": "c3003c93-60cf-4184-b85f-20be14d26dac"
    }'
  ```

  ```typescript JavaScript theme={null}
  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!
  ```
</CodeGroup>

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

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