Webhooks

Overview

Webhooks let you receive real-time notifications when events happen on the Kejue platform. When an event occurs, Kejue sends an HTTP POST request to your configured URL with a JSON payload describing the event.

Event Types

Event	Description
`call.started`	A call has been answered and connected
`call.ended`	A call has ended (before post-call analysis)
`call.analyzed`	Post-call analysis is complete — full results available
`campaign.started`	A campaign has started processing
`campaign.ended`	A campaign has completed, been cancelled, or failed
`campaign.paused`	A campaign has been paused
`campaign.resumed`	A paused campaign has been resumed
`campaign.failed`	A campaign has failed due to an error

Use the wildcard * when creating a subscription to receive all event types.

Payload Format

All webhook payloads follow the same envelope structure:

{
  "event": "call.ended",
  "event_id": "evt_abc123",
  "workspace_id": "ws_xyz",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {},
  "metadata": {}
}

Call Events

call.started

Fired when a call is answered and connected.

{
  "event": "call.started",
  "data": {
    "job_id": "job_123",
    "conversation_id": "conv_456",
    "contact_id": "ct_789",
    "persona_id": "per_abc",
    "campaign_id": null,
    "direction": "outbound",
    "channel": "voice",
    "job_type": "outbound_call",
    "attempt_number": 1,
    "started_at": "2025-01-15T10:30:00Z",
    "contact": {
      "id": "ct_789",
      "name": "John Doe",
      "phone": "+14155551234"
    }
  }
}

call.ended

Fired when a call ends. Includes timing, status, transcript, and recording URL.

This event fires before post-call analysis. Use call.analyzed if you need summary, score, and outcome fields.

{
  "event": "call.ended",
  "data": {
    "job_id": "job_123",
    "contact_id": "ct_789",
    "status": "completed",
    "ended_reason": "agent_hangup",
    "duration_seconds": 295,
    "transcript": "Agent: Hello, this is Sara from...",
    "recording_url": "https://recordings.kejue.co/...",
    "retry": {
      "will_retry": false,
      "next_retry_at": null,
      "attempt_number": 1,
      "max_attempts": 3
    }
  }
}

Status	Description
`completed`	Call connected and conversation took place
`no_answer`	Contact did not answer
`busy`	Line was busy
`failed`	Call failed due to a technical issue
`voicemail`	Call went to voicemail

call.analyzed

Fired after post-call analysis completes. Contains summary, outcome, score, structured data, and tool execution results.

{
  "event": "call.analyzed",
  "data": {
    "call": {
      "id": "job_123",
      "status": "completed",
      "summary": "Discussed pricing plans and scheduled a demo...",
      "outcome_id": "interested",
      "score": 85,
      "structured_data": {
        "interested_product": "Enterprise Plan",
        "budget_range": "$500-1000/mo"
      }
    },
    "contact": {
      "id": "ct_789",
      "name": "John Doe",
      "status": "interested"
    },
    "in_call_tools": [],
    "post_call_actions": []
  }
}

Campaign Events

campaign.ended

Fired when a campaign finishes. Includes full statistics and performance metrics.

{
  "event": "campaign.ended",
  "data": {
    "campaign_id": "camp_abc",
    "campaign_name": "Q1 Outreach",
    "end_reason": "completed",
    "stats": {
      "total_contacts": 500,
      "completed": 420,
      "no_answer": 50,
      "failed": 10,
      "voicemail": 20
    },
    "performance": {
      "connect_rate_percent": 84.0,
      "completion_rate_percent": 86.0,
      "average_call_duration_seconds": 120
    }
  }
}

End Reason	Description
`completed`	All contacts have been processed
`cancelled`	Campaign was manually cancelled
`failed`	Campaign failed due to infrastructure issues

Webhook Signing & Verification

Kejue signs webhook payloads so you can verify they’re authentic.

Method	Headers Sent	How to Verify
hmac_sha256 (default)	`X-Kejue-Signature`, `X-Kejue-Timestamp`	`HMAC-SHA256(secret, "{timestamp}.{body}")`
hmac_sha1	`X-Kejue-Signature`, `X-Kejue-Timestamp`	`HMAC-SHA1(secret, "{timestamp}.{body}")`
bearer	`Authorization: Bearer {secret}`	Compare token
basic_auth	`Authorization: Basic {base64}`	Decode and compare
none	No auth headers	No verification

Verification Examples

const crypto = require('crypto');

function verifyWebhook(body, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.".encode() + body
    expected = hmac.new(
        secret.encode(), signed_payload, hashlib.sha256
    ).hexdigest()
    received = signature.split("=")[1]
    return hmac.compare_digest(expected, received)

Always use constant-time comparison functions to prevent timing attacks.

Delivery & Retries

Setting	Default	Description
Timeout	5 seconds	How long to wait for your server to respond
Max Retries	3	Maximum number of retry attempts
Backoff	500ms	Initial delay between retries (doubles each attempt)

Only 5xx server errors and timeouts trigger retries. 4xx responses are treated as permanent failures and are not retried.

Inline Webhooks

You can pass webhooks inline when creating a call. Inline webhooks override subscription-based webhooks for that specific call.

{
  "contact_id": "ct_789",
  "persona_id": "per_abc",
  "config": {
    "webhooks": [
      {
        "url": "https://your-server.com/webhook",
        "events": ["call.ended", "call.analyzed"],
        "signing_method": "hmac_sha256",
        "secret": "your-secret-key"
      }
    ]
  }
}

Getting Started

Core Concepts

Guides

Overview

Event Types

Payload Format

Call Events

call.started

call.ended

call.analyzed

Campaign Events

campaign.ended

Webhook Signing & Verification

Verification Examples

Delivery & Retries

Inline Webhooks

​Overview

​Event Types

​Payload Format

​Call Events

​call.started

​call.ended

​call.analyzed

​Campaign Events

​campaign.ended

​Webhook Signing & Verification

​Verification Examples

​Delivery & Retries

​Inline Webhooks

Overview

Event Types

Payload Format

Call Events

call.started

call.ended

call.analyzed

Campaign Events

campaign.ended

Webhook Signing & Verification

Verification Examples

Delivery & Retries

Inline Webhooks