CARRIER-GRADE TELEPHONY NETWORK
TELECOM SALES & DEMO: 1 (417) 835-0402
KaiCalls
Help Center

Developer Integration

Outbound Webhooks in KaiCalls.

Stream real-time call and lead events directly to your backend API or server with signed JSON payloads.

Kai sending webhooks from his desk

Real-time JSON

Payloads

Sent via HTTP POST immediately when calls start, update, or end.

HMAC signed

Security

Signatures let your server verify the payload came from KaiCalls.

Auto-retries

Reliability

Failed attempts retry on their own up to 5 times.

Overview

What outbound webhooks do.

Stream phone data into your custom software without polling.

Instant HTTP POST

As soon as a call event occurs, KaiCalls sends a JSON payload to your destination URL.

Complete call data

Data includes the caller number, call length, audio link, transcript, and notes.

Automatic retries

If your server has an error or times out, KaiCalls retries up to 5 times.

Custom headers

You can add custom header keys to send with each request.

Event types

Events you can subscribe to.

Pick only the events your application needs.

call.started

Fires the instant an inbound call connects to Kai.

call.completed

Fires when a call hangs up. Contains the recording link and summary.

lead.created

Fires when Kai successfully extracts a caller name and contact info.

Setup

How to configure a webhook.

Add your endpoint URL in three quick steps.

  1. 1

    Open Connections in KaiCalls

    In KaiCalls, go to Connections > Webhooks.
  2. 2

    Enter your Endpoint URL

    Paste your HTTPS destination URL (e.g. https://api.yourdomain.com/webhooks/kaicalls).
  3. 3

    Copy your Webhook Secret

    Save the signing secret shown on screen. Save it safely in your server config.
  4. 4

    Click Send Test Payload

    KaiCalls sends a test payload to check that your server says OK.

Security

Verify webhook signatures.

Ensure payloads come from KaiCalls, not an attacker.

HMAC SHA-256 header

Each request includes a x-kaicalls-signature header. Compute the HMAC SHA-256 hash of the raw request body using your secret key. Check the signature before handling the data.

Verification

How to prove it worked.

Check delivery in Systems Monitor.

  • Click Send Test on the Webhooks connection card.
  • Check your server logs: Confirm your endpoint received the POST request and returned HTTP 200.
  • Place a live test call to your KaiCalls number.
  • Open KaiCalls > Systems Monitor: Confirm the call.completed webhook shows status 200 OK.

Troubleshooting

Fix common webhook delivery issues.

Endpoint returns 403 or 401

Ensure your server firewall allows incoming requests or verify your custom auth header matches what your server expects.

Server timed out

Your endpoint must respond with HTTP 200 within 5 seconds. Offload heavy processing to a background worker queue.

Signature check fails

Use the raw unparsed request body string when calculating HMAC. Parsing JSON before hashing will break the signature match.

HTTPS required

KaiCalls only delivers webhooks over encrypted HTTPS connections. Plain HTTP endpoints are rejected for security.