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
| Event | When it is sent |
|---|---|
| CALL_RECEIVED | When a call comes in. Sent as an incoming-call notice before the AI answers or before the call is handed to staff. |
| CALL_COMPLETED | When a call has ended and its transcription and summary are done. |
| MESSAGE_RECEIVED | When a customer sends a message. |
| SEND_RESULT | When the delivery result of a message you sent is available. |
| INTAKE | When an AI agent saves, changes or cancels a record-type intake. Sent immediately, during the call. |
| AI_OUTBOUND | When 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 -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.
{
"eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
"eventType": "CALL_COMPLETED",
"timestamp": "2026-11-01T06:00:00.000Z",
"data": { }
}| Field | Description |
|---|---|
| eventId | Unique ID of a single notification (UUID). It stays the same on resend. Use it to filter duplicates. |
| eventType | Event name |
| timestamp | Time sent (ISO 8601) |
| data | Event-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.
{
"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.
{
"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.
{
"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").
{
"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.
{
"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.
| Header | Value |
|---|---|
| X-Webhook-Timestamp | Time sent (Unix seconds) |
| X-Webhook-Signature | v1= followed by the hex digest of HMAC-SHA256(secret, "<timestamp>.<raw body>") |
- Take the body as the exact bytes received, before parsing. If you parse and re-serialize it, the signature will not match.
- Reject the request if the timestamp differs from the current time by more than 5 minutes.
- Use the secret as the key exactly as given, including the
whsec_prefix. Get it withGET /webhook/secret. - Compare in constant time, and respond with 401 if they differ.
- If it passes, use
eventIdto skip notifications you have already processed.
Node.js (Express)
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)
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', 200Reissue 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).
eventIdstays the same on resend. A notification that was marked failed because your response was slow can also arrive again, so filter byeventId.- If all three attempts fail, we stop sending. Fetch missed calls again with the call history API.
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 -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.
- 01Create an account
- 02Get a phone number
- 03Connect your agent and take the first call
