Skip to main content
POST
Create a webhook endpoint

Authorizations

Authorization
string
header
required

An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.

Headers

Idempotency-Key
string
required

A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.

Maximum string length: 255
Kallabot-Version
enum<string>

The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.

Available options:
2026-11-07
Example:

"2026-11-07"

Body

application/json
url
string
required

The HTTPS URL Kallabot POSTs signed events to.

Maximum string length: 2048
events
string[]
required

Event types to send (from GET /v1/webhooks/event-types), a whole category such as call.*, or * for everything.

Required array length: 1 - 60 elements
name
string | null

A label for this endpoint.

Required string length: 1 - 120
description
string | null

A note for your team.

Maximum string length: 280
agent_ids
string[]

Only send events about these agents. Empty sends events about every agent.

Maximum array length: 50
include_content
boolean
default:false

Include conversation content (transcripts, messages, phone numbers) in event payloads. Off by default: events then carry ids you fetch with your API key.

Response

Successful Response

id
string
required

The endpoint id.

url
string
required

Where events are sent.

status
string
required

active or disabled.

events
string[]
required

The event types (or patterns) it receives.

secret_hint
string
required

The last characters of the signing secret.

revision
integer
required

Send this back as revision on an update.

created_at
string
required

ISO 8601 time it was created.

updated_at
string
required

ISO 8601 time it last changed.

name
string | null

The endpoint's label.

description
string | null

A note for your team.

disabled_reason
string | null

Why Kallabot turned it off, when it did.

agent_ids
string[]

Only events about these agents; empty is all.

include_content
boolean
default:false

Whether payloads carry conversation content.

api_version
string | null

The event payload version this endpoint receives.

secret_format
string
default:standard

standard (Standard Webhooks whsec_…) or legacy (rotate it).

secret_previous_expires_at
string | null

When the previous secret stops signing, during a rotation's grace period.

consecutive_failures
integer
default:0

Deliveries failed in a row.

failing_since
string | null

When the current run of failures started.

last_success_at
string | null

The last successful delivery.

secret
string | null

The signing secret. Only on create and rotate, and never on a replay.