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

Setting Up Webhooks

1. Create a Webhook Endpoint

Create your developer account at kallglot.com, then create a webhook endpoint in the Developer Portal:

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

2. Configure Your Server

Set up an endpoint to receive webhook events:

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:

{
  "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)

If your endpoint returns a non-2xx status or times out, Kallglot will retry the webhook. See Retry Policy for details.

Best Practices

Respond quickly

Process webhooks asynchronously. Return a 200 response immediately, then process the event in a background job.

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

Handle duplicate events

The same event may be delivered multiple times. Use the id field to deduplicate:

async function processEvent(event) {
  if (await alreadyHandled(event.id)) {
    return;
  }

  await handleEvent(event);
  await markHandled(event.id, { ttlSeconds: 86400 });
}

Verify signatures

Always verify webhook signatures to ensure events are from Kallglot. See Signatures.

Log all events

Log incoming webhooks for debugging and audit purposes:

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

Monitor delivery

Check the Developer Portal for webhook delivery status and failures. Set up alerts for repeated failures.

Testing Webhooks

Using the Developer Portal

Go to Webhooks > select your endpoint
Click Send Test Event
Choose an event type
View the delivery log

Using ngrok for Local Development

# Start ngrok
ngrok http 3000

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

Using the CLI

# 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

​Webhooks

​How Webhooks Work

​Setting Up Webhooks

​1. Create a Webhook Endpoint

​2. Configure Your Server

​3. Test Your Endpoint

​Event Structure

​Event Categories

​Session Events

​Transcript Events

​Recording Events

​Analysis Events

​Provider Events

​Endpoint Requirements

​Best Practices

​Testing Webhooks

​Using the Developer Portal

​Using ngrok for Local Development

​Using the CLI

Webhooks

How Webhooks Work

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Configure Your Server

3. Test Your Endpoint

Event Structure

Event Categories

Session Events

Transcript Events

Recording Events

Analysis Events

Provider Events

Endpoint Requirements

Best Practices

Testing Webhooks

Using the Developer Portal

Using ngrok for Local Development

Using the CLI