Skip to main content

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

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:
  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: 
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
  }
}
FieldDescription
idUnique event identifier
typeEvent type (e.g., session.ended)
api_versionAPI version that generated the event
created_atWhen the event was created
dataEvent-specific payload

​
Event Categories

​
Session Events

EventDescription
session.createdA new session was created
session.startedSession became active
session.endedSession ended

​
Transcript Events

EventDescription
transcript.readyFull transcript is available
transcript.segmentNew transcript segment (real-time)

​
Recording Events

EventDescription
recording.readyRecording is available for download
recording.failedRecording generation failed

​
Analysis Events

EventDescription
analysis.completeAnalysis results are ready
analysis.failedAnalysis failed

​
Provider Events

EventDescription
session.provider.connectedProvider call connected
session.provider.disconnectedProvider 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

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');
});
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 });
}
Always verify webhook signatures to ensure events are from Kallglot. See Signatures.
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()
  });
  // ...
});
Check the Developer Portal for webhook delivery status and failures. Set up alerts for repeated failures.

​
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

# 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