Webhooks
웹훅
전화가 오고, 통화가 끝나고, 문자가 오가면 등록한 주소로 HTTP POST 를 보냅니다. 이벤트 하나에 주소 하나를 등록합니다. 모든 알림에는 서명이 붙습니다.
01
이벤트 목록
| 이벤트 | 언제 오나 |
|---|---|
| CALL_RECEIVED | 전화가 들어왔을 때. AI 응대 전이나 직원 연결 전에 착신 알림으로 옵니다. |
| CALL_COMPLETED | 통화가 끝나고 받아쓰기 · 요약이 끝났을 때. |
| MESSAGE_RECEIVED | 고객이 문자를 보냈을 때. |
| SEND_RESULT | 보낸 문자의 발송 결과가 나왔을 때. |
| INTAKE | AI 상담원이 기록형 접수를 저장 · 변경 · 취소할 때. 통화 중에 바로 옵니다. |
| AI_OUTBOUND | AI 발신 통화가 끝났을 때, 그리고 분석이 끝났을 때. data.type 으로 나뉩니다. |
등록은 POST /webhook 에 eventType 과 https url 을 보냅니다. 웹 콘솔에서도 같은 설정을 다룹니다. 웹훅 설정
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
공통 본문
모든 이벤트는 같은 봉투에 담겨 옵니다. 이벤트마다 다른 것은 data 뿐입니다.
{
"eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
"eventType": "CALL_COMPLETED",
"timestamp": "2026-11-01T06:00:00.000Z",
"data": { }
}| 필드 | 설명 |
|---|---|
| eventId | 알림 하나의 고유 ID (UUID). 다시 보내도 같은 값입니다. 이 값으로 중복을 거릅니다. |
| eventType | 이벤트 이름 |
| timestamp | 보낸 시각 (ISO 8601) |
| data | 이벤트별 내용 |
03
페이로드 예시
필드를 줄인 예시입니다. 전체 필드 설명은 API 문서의 이벤트 목록에 있습니다.
CALL_RECEIVED
handOffReason 은 AI 응대 중 직원 연결로 바뀔 때만 들어갑니다.
{
"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": "매장A",
"channelId": 100,
"fromNumber": "01012345678",
"fromName": "홍길동 (매장A)",
"toNumber": "07012345678",
"handOffReason": "고객이 직원 연결을 요청함",
"receivedAt": "2026-03-12T02:40:00.000Z"
}
}CALL_COMPLETED
status 는 ANSWERED · MISSED · REJECTED · UNKNOWN, tag 는 AI · DIRECT · AI_TO_DIRECT · UNKNOWN 입니다. 녹음 URL 은 만료 시각이 있는 임시 주소라 만료 전에 내려받아야 합니다.
{
"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": "예약 변경 요청을 접수하고 변경 가능한 시간대를 안내함",
"sttAI": [
{ "role": "agent", "text": "안녕하세요. KAT Cloud입니다.", "timestamp": 1.2 }
],
"sttDirect": [
{ "role": "customer", "text": "직원 연결 부탁드립니다.", "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 는 내 KAT Cloud 번호, senderPhoneNumber 는 고객 번호입니다.
{
"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": "안녕하세요, 예약 문의드립니다.",
"imageList": [],
"receivedAt": "2024-03-05T10:30:00.000Z"
}
}SEND_RESULT
data.chatId 는 문자를 보낼 때 받은 chatId 와 같습니다. sendStatus 는 SUCCESS · FAILED 입니다.
{
"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": "예약이 확정되었습니다.",
"chatType": "SMS",
"sendStatus": "SUCCESS",
"resultStatus": "4100",
"resultMessage": "전달",
"sentAt": "2024-03-05T10:30:05.000Z"
}
}AI_OUTBOUND
요청 하나에 ai_outbound.call.ended 다음 ai_outbound.analysis.completed 가 옵니다. 순서가 바뀌어 와도 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
서명 검증
모든 알림에 두 헤더가 붙습니다. 검증하면 KAT Cloud 가 보낸 알림인지, 본문이 바뀌지 않았는지 알 수 있습니다.
| 헤더 | 값 |
|---|---|
| X-Webhook-Timestamp | 보낸 시각 (유닉스 초) |
| X-Webhook-Signature | v1= 뒤에 HMAC-SHA256(비밀값, "<timestamp>.<본문 원문>") 의 16진수 |
- 본문을 파싱하기 전에 받은 바이트 그대로 가져옵니다. 파싱했다가 다시 직렬화하면 서명이 맞지 않습니다.
- timestamp 가 지금과 5분 넘게 차이 나면 거절합니다.
- 비밀값은
whsec_까지 포함한 문자열 그대로 키로 씁니다.GET /webhook/secret으로 받습니다. - 상수 시간 비교로 맞춰 보고, 다르면 401 로 답합니다.
- 통과하면
eventId로 이미 처리한 알림인지 거릅니다.
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
const WEBHOOK_SECRET = process.env.KATCLOUD_WEBHOOK_SECRET; // 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.json() 이 아니라 express.raw() — 받은 바이트 그대로 검증한다
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'));
// event.eventId 로 이미 처리한 알림인지 거른 뒤 처리한다
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'] # 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() # 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)
# event['eventId'] 로 이미 처리한 알림인지 거른 뒤 처리한다
return 'OK', 200비밀값은 POST /webhook/secret/rotate 로 다시 발급합니다. 그 뒤 알림부터 새 값으로 서명하므로, 바꾸는 동안에는 새 값 · 이전 값 중 하나로 맞으면 통과시키세요. 비밀값 조회 · 재발급
05
재시도
- 2xx 로 답하면 성공입니다. 10초 안에 답하지 않거나 2xx 가 아니면 실패로 봅니다.
- 실패하면 다시 보냅니다. 처음을 포함해 최대 3번입니다(첫 실패 약 5초 뒤, 그다음 약 15초 뒤).
- 다시 보내도
eventId는 같습니다. 응답이 늦어 실패로 처리된 알림도 다시 올 수 있으니eventId로 거르세요. - 세 번 모두 실패하면 더는 보내지 않습니다. 놓친 통화는 통화 기록 API 로 다시 가져옵니다.
06
디버깅
POST /webhook/{webhookId}/test로 시험 알림을 보냅니다. 실제 알림과 같은 비밀값으로 서명하고, 본문에"isTest": true가 들어갑니다. 응답으로 상태 코드와 응답 시간을 돌려줍니다.- CALL_RECEIVED · CALL_COMPLETED 시험 알림은 data 가 빈 객체입니다. 빈 data 도 받아 넘기게 짜 두세요.
- 먼저 200 으로 답하고, 오래 걸리는 처리는 큐로 넘깁니다. 10초를 넘기면 실패로 보고 다시 보냅니다.
- 서명이 계속 틀리면 본문 파서를 확인하세요. JSON 미들웨어가 먼저 본문을 읽으면 원문이 바뀝니다.
- 통화 완료 알림은 대화 내용 때문에 본문이 클 수 있습니다. 본문 크기 제한을 넉넉히 둡니다.
- 녹음 URL 은 만료 시각(expiresAt)이 있습니다. 알림을 받으면 바로 내려받으세요.
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 }- 01계정 만들기
- 02전화번호 발급
- 03에이전트 연결하고 첫 통화
