유사 사이트를 조심하세요. 한국에이아이통신(주)의 공식 사이트는 katel.kr · katcloud.kr · zerocall.kr · aicallpay.com 입니다.공식 채널 확인
KAT CloudKOEN로그인

Webhooks

웹훅

전화가 오고, 통화가 끝나고, 문자가 오가면 등록한 주소로 HTTP POST 를 보냅니다. 이벤트 하나에 주소 하나를 등록합니다. 모든 알림에는 서명이 붙습니다.

01

이벤트 목록

이벤트언제 오나
CALL_RECEIVED전화가 들어왔을 때. AI 응대 전이나 직원 연결 전에 착신 알림으로 옵니다.
CALL_COMPLETED통화가 끝나고 받아쓰기 · 요약이 끝났을 때.
MESSAGE_RECEIVED고객이 문자를 보냈을 때.
SEND_RESULT보낸 문자의 발송 결과가 나왔을 때.
INTAKEAI 상담원이 기록형 접수를 저장 · 변경 · 취소할 때. 통화 중에 바로 옵니다.
AI_OUTBOUNDAI 발신 통화가 끝났을 때, 그리고 분석이 끝났을 때. data.type 으로 나뉩니다.

등록은 POST /webhook 에 eventType 과 https url 을 보냅니다. 웹 콘솔에서도 같은 설정을 다룹니다. 웹훅 설정

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

공통 본문

모든 이벤트는 같은 봉투에 담겨 옵니다. 이벤트마다 다른 것은 data 뿐입니다.

JSON
{
  "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 응대 중 직원 연결로 바뀔 때만 들어갑니다.

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": "매장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 은 만료 시각이 있는 임시 주소라 만료 전에 내려받아야 합니다.

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": "예약 변경 요청을 접수하고 변경 가능한 시간대를 안내함",
    "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 는 고객 번호입니다.

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": "안녕하세요, 예약 문의드립니다.",
    "imageList": [],
    "receivedAt": "2024-03-05T10:30:00.000Z"
  }
}

SEND_RESULT

data.chatId 는 문자를 보낼 때 받은 chatId 와 같습니다. sendStatus 는 SUCCESS · FAILED 입니다.

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": "예약이 확정되었습니다.",
    "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 가 작은 것으로 최신 상태를 덮지 마세요.

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

서명 검증

모든 알림에 두 헤더가 붙습니다. 검증하면 KAT Cloud 가 보낸 알림인지, 본문이 바뀌지 않았는지 알 수 있습니다.

헤더값
X-Webhook-Timestamp보낸 시각 (유닉스 초)
X-Webhook-Signaturev1= 뒤에 HMAC-SHA256(비밀값, "<timestamp>.<본문 원문>") 의 16진수
  1. 본문을 파싱하기 전에 받은 바이트 그대로 가져옵니다. 파싱했다가 다시 직렬화하면 서명이 맞지 않습니다.
  2. timestamp 가 지금과 5분 넘게 차이 나면 거절합니다.
  3. 비밀값은 whsec_ 까지 포함한 문자열 그대로 키로 씁니다. GET /webhook/secret 으로 받습니다.
  4. 상수 시간 비교로 맞춰 보고, 다르면 401 로 답합니다.
  5. 통과하면 eventId 로 이미 처리한 알림인지 거릅니다.

Node.js (Express)

JavaScript
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)

Python
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
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

오늘 만든 AI에게
전화번호 연결

가입 후 7일 동안 개인 플랜을 무료로 쓸 수 있습니다. 번호를 발급하고 첫 전화를 받아보세요.

이미 계정이 있나요? 로그인

  1. 01계정 만들기
  2. 02전화번호 발급
  3. 03에이전트 연결하고 첫 통화