Beware of lookalike sites. The official sites of Korea AI Telecom Inc. are katel.kr, katcloud.kr, zerocall.kr and aicallpay.com.Verify official channels
KAT CloudKOENLog in

Webhooks

Webhooks

When a call comes in, a call ends, or messages are sent and received, we send an HTTP POST to the URL you registered. Register one URL per event. Every notification is signed.

01

Event list

EventWhen it is sent
CALL_RECEIVEDWhen a call comes in. Sent as an incoming-call notice before the AI answers or before the call is handed to staff.
CALL_COMPLETEDWhen a call has ended and its transcription and summary are done.
MESSAGE_RECEIVEDWhen a customer sends a message.
SEND_RESULTWhen the delivery result of a message you sent is available.
INTAKEWhen an AI agent saves, changes or cancels a record-type intake. Sent immediately, during the call.
AI_OUTBOUNDWhen an AI outbound call ends, and when its analysis is done. Distinguished by data.type.

To register, send an eventType and an https url to POST /webhook. The web console manages the same settings. Webhook configuration

cURL
curl -X POST "https://studio-gateway.zerocall.kr/webhook" \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventType": "MESSAGE_RECEIVED", "url": "https://my.app/kat/webhook" }'

02

Common body

Every event comes in the same envelope. Only data differs by event.

JSON
{
  "eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
  "eventType": "CALL_COMPLETED",
  "timestamp": "2026-11-01T06:00:00.000Z",
  "data": { }
}
FieldDescription
eventIdUnique ID of a single notification (UUID). It stays the same on resend. Use it to filter duplicates.
eventTypeEvent name
timestampTime sent (ISO 8601)
dataEvent-specific content

03

Payload examples

These examples are trimmed. For descriptions of every field, see the event list in the API docs.

CALL_RECEIVED

handOffReason is included only when an AI-handled call is being handed to staff.

JSON
{
  "eventId": "c2b8d4f6-1a3e-4c5d-8e7f-9a0b1c2d3e4f",
  "eventType": "CALL_RECEIVED",
  "timestamp": "2026-03-12T02:40:00.000Z",
  "data": {
    "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
    "groupId": 1,
    "groupName": "Store A",
    "channelId": 100,
    "fromNumber": "01012345678",
    "fromName": "Hong Gildong (Store A)",
    "toNumber": "07012345678",
    "handOffReason": "Customer asked to speak to staff",
    "receivedAt": "2026-03-12T02:40:00.000Z"
  }
}

CALL_COMPLETED

status is ANSWERED, MISSED, REJECTED or UNKNOWN; tag is AI, DIRECT, AI_TO_DIRECT or UNKNOWN. Recording URLs are temporary and expire, so download them before they expire.

JSON
{
  "eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
  "eventType": "CALL_COMPLETED",
  "timestamp": "2026-03-12T02:45:30.000Z",
  "data": {
    "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
    "groupId": 1,
    "channelId": 100,
    "fromNumber": "01012345678",
    "toNumber": "07012345678",
    "isInbound": true,
    "status": "ANSWERED",
    "tag": "AI_TO_DIRECT",
    "duration": 96,
    "summary": "Took a reservation change request and explained the available time slots",
    "sttAI": [
      { "role": "agent", "text": "Hello, this is KAT Cloud.", "timestamp": 1.2 }
    ],
    "sttDirect": [
      { "role": "customer", "text": "Please connect me to a staff member.", "timestamp": 30.1 }
    ],
    "recordings": {
      "ai": {
        "url": "https://storage.example.com/recording-ai.wav",
        "expiresAt": "2026-03-12T03:45:30.000Z",
        "contentLength": 1234567,
        "contentType": "audio/wav"
      }
    },
    "startedAt": "2026-03-12T02:40:00.000Z",
    "completedAt": "2026-03-12T02:41:36.000Z"
  }
}

MESSAGE_RECEIVED

phoneNumber is your KAT Cloud number; senderPhoneNumber is the customer's number.

JSON
{
  "eventId": "5d1c9a3e-2b7f-4e6a-8c0d-1f2e3a4b5c6d",
  "eventType": "MESSAGE_RECEIVED",
  "timestamp": "2024-03-05T10:30:00.000Z",
  "data": {
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "groupId": 1,
    "channelId": 100,
    "phoneNumber": "07012345678",
    "senderPhoneNumber": "01098765432",
    "content": "Hi, I have a question about a reservation.",
    "imageList": [],
    "receivedAt": "2024-03-05T10:30:00.000Z"
  }
}

SEND_RESULT

data.chatId matches the chatId you received when sending the message. sendStatus is SUCCESS or FAILED. resultMessage is passed through as returned by the carrier, in Korean (here "전달" means "delivered").

JSON
{
  "eventId": "a7e3f0b2-6c1d-4f8e-9a2b-3c4d5e6f7a8b",
  "eventType": "SEND_RESULT",
  "timestamp": "2024-03-05T10:30:05.000Z",
  "data": {
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "groupId": 1,
    "channelId": 100,
    "sendPhoneNumber": "07012345678",
    "recvPhoneNumber": "01098765432",
    "content": "Your reservation is confirmed.",
    "chatType": "SMS",
    "sendStatus": "SUCCESS",
    "resultStatus": "4100",
    "resultMessage": "전달",
    "sentAt": "2024-03-05T10:30:05.000Z"
  }
}

AI_OUTBOUND

Each request gets ai_outbound.call.ended followed by ai_outbound.analysis.completed. Even if they arrive out of order, do not overwrite the latest state with one that has a smaller sequence.

JSON
{
  "eventId": "2f3a8c41-7b6e-4d0a-9c1e-5a7b3d2e1f60",
  "eventType": "AI_OUTBOUND",
  "timestamp": "2026-11-05T03:00:05.000Z",
  "data": {
    "type": "ai_outbound.call.ended",
    "sequence": 1,
    "schemaVersion": 1,
    "occurredAt": "2026-11-05T03:00:00.000Z",
    "requestId": "9f0c3a52-1111-4a5b-8c9d-000000000001",
    "status": "COMPLETED",
    "answered": true,
    "durationSeconds": 140,
    "analysisStatus": "PENDING",
    "settlementStatus": "PENDING"
  }
}

04

Signature verification

Every notification carries two headers. Verifying them tells you the notification was sent by KAT Cloud and the body was not altered.

HeaderValue
X-Webhook-TimestampTime sent (Unix seconds)
X-Webhook-Signaturev1= followed by the hex digest of HMAC-SHA256(secret, "<timestamp>.<raw body>")
  1. Take the body as the exact bytes received, before parsing. If you parse and re-serialize it, the signature will not match.
  2. Reject the request if the timestamp differs from the current time by more than 5 minutes.
  3. Use the secret as the key exactly as given, including the whsec_ prefix. Get it with GET /webhook/secret.
  4. Compare in constant time, and respond with 401 if they differ.
  5. If it passes, use eventId to skip notifications you have already processed.

Node.js (Express)

JavaScript
const crypto = require('crypto');
const express = require('express');

const app = express();
const WEBHOOK_SECRET = process.env.KATCLOUD_WEBHOOK_SECRET; // starts with whsec_
const TOLERANCE_SECONDS = 5 * 60;

function verify(rawBody, timestamp, signature) {
  if (!timestamp || !signature) return false;
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > TOLERANCE_SECONDS) return false;

  const expected = 'v1=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw(), not express.json() — verify the bytes exactly as received
app.post('/webhook', express.raw({ type: 'application/json', limit: '5mb' }), (req, res) => {
  const ok = verify(req.body, req.get('X-Webhook-Timestamp'), req.get('X-Webhook-Signature'));
  if (!ok) return res.status(401).send('invalid signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // Use event.eventId to skip notifications you have already processed, then handle it
  res.status(200).send('OK');
});

app.listen(3000);

Python (Flask)

Python
import hashlib, hmac, json, os, time
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['KATCLOUD_WEBHOOK_SECRET']  # starts with whsec_
TOLERANCE_SECONDS = 5 * 60


def verify(raw_body, timestamp, signature):
    if not timestamp or not signature:
        return False
    try:
        ts = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False
    digest = hmac.new(
        WEBHOOK_SECRET.encode(),
        timestamp.encode() + b'.' + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(('v1=' + digest).encode(), signature.encode())


@app.post('/webhook')
def webhook():
    raw_body = request.get_data()  # raw bytes, not get_json()
    if not verify(raw_body,
                  request.headers.get('X-Webhook-Timestamp'),
                  request.headers.get('X-Webhook-Signature')):
        return 'invalid signature', 401

    event = json.loads(raw_body)
    # Use event['eventId'] to skip notifications you have already processed, then handle it
    return 'OK', 200

Reissue the secret with POST /webhook/secret/rotate. Notifications from then on are signed with the new value, so during the switch, accept a notification if it matches either the new or the previous value. Get / reissue the secret

05

Retries

  • A 2xx response means success. No response within 10 seconds, or a non-2xx response, counts as a failure.
  • On failure we resend, up to 3 attempts in total including the first (about 5 seconds after the first failure, then about 15 seconds later).
  • eventId stays the same on resend. A notification that was marked failed because your response was slow can also arrive again, so filter by eventId.
  • If all three attempts fail, we stop sending. Fetch missed calls again with the call history API.

Delivery and resend·Call history

06

Debugging

  • Send a test notification with POST /webhook/{webhookId}/test. It is signed with the same secret as real notifications, and the body includes "isTest": true. The response returns the status code and response time.
  • Test notifications for CALL_RECEIVED and CALL_COMPLETED have an empty data object. Make sure your handler accepts an empty data object.
  • Respond with 200 first and hand long-running work to a queue. Taking over 10 seconds counts as a failure and triggers a resend.
  • If signatures keep failing, check your body parser. If JSON middleware reads the body first, the raw body changes.
  • Call completed notifications can be large because they include the conversation. Set a generous body size limit.
  • Recording URLs have an expiry time (expiresAt). Download them as soon as you receive the notification.
cURL
curl -X POST "https://studio-gateway.zerocall.kr/webhook/$WEBHOOK_ID/test" \
  -H "x-api-key: $KAT_API_KEY"
# → { "success": true, "statusCode": 200, "responseTime": 150, "error": null }

Get started

Give the AI you built today
a phone number

Use the Personal plan free for 7 days after you sign up. Get a number and take your first call.

Already have an account? Log in

The console (app.katcloud.kr) is in Korean.

  1. 01Create an account
  2. 02Get a phone number
  3. 03Connect your agent and take the first call