Skip to main content

​
Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Kallglot account. Instead of polling the API, Kallglot sends HTTP POST requests to your configured endpoint.

​
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) {
  // Check if already processed
  if (await redis.get(`webhook:${event.id}`)) {
    return; // Already processed
  }

  // Process the event
  await handleEvent(event);

  // Mark as processed
  await redis.set(`webhook:${event.id}`, '1', 'EX', 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