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

# Webhooks Overview

> Receive real-time notifications for events

# Webhooks

Use webhooks when your backend should react to call lifecycle, recordings, delivery failures, etc. You register an HTTPS URL, subscribe to events, verify each `POST`, and acknowledge with `2xx` quickly so Kallglot stops retrying.

## How Webhooks Work

```mermaid theme={null}
sequenceDiagram
    participant Kallglot
    participant YourServer

    Kallglot->>YourServer: POST /webhooks (event payload)
    YourServer->>YourServer: Verify signature
    YourServer->>YourServer: Process event
    YourServer-->>Kallglot: 200 OK

    Note over Kallglot,YourServer: If no 2xx response, retry with backoff
```

## Setting Up Webhooks

### 1. Create a Webhook Endpoint

Create your developer account at [kallglot.com](https://www.kallglot.com/users/sign_up), then create a webhook endpoint in the Developer Portal:

1. Go to **Webhooks** > **Add Endpoint**
2. Enter your endpoint URL (must be HTTPS)
3. Select which events to receive
4. Save and copy the signing secret

### 2. Configure Your Server

Set up an endpoint to receive webhook events:

```javascript theme={null}
import express from 'express';
import crypto from 'crypto';

const app = express();

// Use raw body for signature verification
app.post('/webhooks/kallglot', express.raw({ type: 'application/json' }), (req, res) => {
  const signatureHeader = req.headers['kallglot-signature'];

  // Verify signature (see Signatures page for details)
  if (!verifyWebhook(req.body.toString(), signatureHeader, process.env.KALLGLOT_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  // Handle the event
  switch (event.type) {
    case 'session.ended':
      handleSessionEnded(event.data);
      break;
    case 'analysis.complete':
      handleAnalysisComplete(event.data);
      break;
    // ... handle other events
  }

  // Respond quickly
  res.status(200).send('OK');
});
```

### 3. Test Your Endpoint

Use the Developer Portal to send test events to your endpoint before going live.

## Event Structure

All webhook events follow this structure:

```json theme={null}
{
  "id": "evt_01HXYZ123456789",
  "type": "session.ended",
  "api_version": "v1",
  "created_at": "2026-03-26T11:04:20Z",
  "data": {
    "id": "sess_01HXYZ123456789",
    "object": "session",
    "status": "ended",
    "duration": 245.3
    // ... event-specific data
  }
}
```

| Field         | Description                          |
| ------------- | ------------------------------------ |
| `id`          | Unique event identifier              |
| `type`        | Event type (e.g., `session.ended`)   |
| `api_version` | API version that generated the event |
| `created_at`  | When the event was created           |
| `data`        | Event-specific payload               |

## Event Categories

### Session Events

| Event             | Description               |
| ----------------- | ------------------------- |
| `session.created` | A new session was created |
| `session.started` | Session became active     |
| `session.ended`   | Session ended             |

### Transcript Events

| Event                | Description                        |
| -------------------- | ---------------------------------- |
| `transcript.ready`   | Full transcript is available       |
| `transcript.segment` | New transcript segment (real-time) |

### Recording Events

| Event              | Description                         |
| ------------------ | ----------------------------------- |
| `recording.ready`  | Recording is available for download |
| `recording.failed` | Recording generation failed         |

### Analysis Events

| Event               | Description                |
| ------------------- | -------------------------- |
| `analysis.complete` | Analysis results are ready |
| `analysis.failed`   | Analysis failed            |

### Provider Events

| Event                           | Description                |
| ------------------------------- | -------------------------- |
| `session.provider.connected`    | Provider call connected    |
| `session.provider.disconnected` | Provider call disconnected |

## Endpoint Requirements

Your webhook endpoint must:

* Accept HTTPS POST requests
* Respond within 30 seconds
* Return a 2xx status code on success
* Be publicly accessible (no localhost)

<Warning>
  If your endpoint returns a non-2xx status or times out, Kallglot will retry the webhook. See [Retry Policy](/webhooks/retry-policy) for details.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Process webhooks asynchronously. Return a 200 response immediately, then process the event in a background job.

    ```javascript theme={null}
    app.post('/webhooks/kallglot', (req, res) => {
      // Verify signature
      // ...

      // Queue for async processing
      queue.add('process-webhook', req.body);

      // Respond immediately
      res.status(200).send('OK');
    });
    ```
  </Accordion>

  <Accordion title="Handle duplicate events">
    The same event may be delivered multiple times. Use the `id` field to deduplicate:

    ```javascript theme={null}
    async function processEvent(event) {
      if (await alreadyHandled(event.id)) {
        return;
      }

      await handleEvent(event);
      await markHandled(event.id, { ttlSeconds: 86400 });
    }
    ```
  </Accordion>

  <Accordion title="Verify signatures">
    Always verify webhook signatures to ensure events are from Kallglot. See [Signatures](/webhooks/signatures).
  </Accordion>

  <Accordion title="Log all events">
    Log incoming webhooks for debugging and audit purposes:

    ```javascript theme={null}
    app.post('/webhooks/kallglot', (req, res) => {
      console.log('Webhook received:', {
        id: req.body.id,
        type: req.body.type,
        timestamp: new Date().toISOString()
      });
      // ...
    });
    ```
  </Accordion>

  <Accordion title="Monitor delivery">
    Check the Developer Portal for webhook delivery status and failures. Set up alerts for repeated failures.
  </Accordion>
</AccordionGroup>

## Testing Webhooks

### Using the Developer Portal

1. Go to **Webhooks** > select your endpoint
2. Click **Send Test Event**
3. Choose an event type
4. View the delivery log

### Using ngrok for Local Development

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the ngrok URL in Developer Portal
# https://abc123.ngrok.io/webhooks/kallglot
```

### Using the CLI

```bash theme={null}
# Install Kallglot CLI
npm install -g @kallglot/cli

# Listen for webhooks locally
kallglot webhooks listen --port 3000

# Trigger a test event
kallglot webhooks trigger session.ended
```