# Webhook 개요 (/docs/webhooks)

## 개요

한국AI통신은 통화 및 메시지 관련 이벤트를 실시간으로 알려주는 알림을 제공합니다.
이벤트가 발생하면 설정된 URL로 HTTP POST 요청이 전송되며, 서버는 `200` 또는 `204`로 응답합니다.

## 종류

### Status Callback

통화 상태가 변경될 때마다 (ringing → answered → completed, 또는 busy/rejected) 이벤트가 전송됩니다.

- **발신(outbound)**: `calls.create()`의 `status_callback` 파라미터로 **통화별** 설정합니다.
- **수신(inbound)**: 전화번호 설정의 `status_callback`(대시보드 "수신 통화 상태 webhook" 또는 번호 API)에 **번호별**로 미리 등록합니다.

자세한 내용은 [Status Callback 문서](/docs/webhooks/status)를 참고하세요.

### Message Webhook

메시지 관련 이벤트(발송 완료, 실패, 수신)가 발생하면 알림이 전송됩니다.
문자(SMS/LMS/MMS)와 카카오 알림톡·브랜드 메시지가 같은 이벤트를 씁니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Message Webhook 문서](/docs/webhooks/message)를 참고하세요.

### Recording Webhook

통화 녹음 파일이 GCS 에 업로드되거나 업로드에 실패했을 때 알림이 전송되며, API key 인증으로 다운로드 가능한 `RecordingUrl` 이 포함됩니다.
**부가서비스 → 통화 녹음** 이 활성화되어 있어야 동작합니다. 녹음 설정(받기 전 구간부터 녹음 등)은 [통화 녹음](/docs/call-recording) 을 보세요.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Recording Webhook 문서](/docs/webhooks/recording)를 참고하세요.

### Call Flow Webhook

콜 플로우(결정형 ARS)가 통화에서 수집한 값 — 발신자가 누른 번호, 녹음한 음성, HTTP 블럭이 조회한 값 — 이
통화 종료 시 `callflow.ended` 이벤트로 한 번에 전송됩니다. 끝까지 진행한 통화와 중간에 끊긴 통화 모두
전송되며 `Status`(completed / abandoned)로 구분합니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Call Flow Webhook 문서](/docs/webhooks/callflow)를 참고하세요.

### Transcript Webhook

통화 전사(STT)가 완료되거나 실패했을 때 알림이 전송되며, 전사 결과 JSON의 GCS 서명 URL이 포함됩니다.
**부가서비스 → 통화 받아쓰기** 를 활성화해야 동작하는 유료 기능입니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Transcript Webhook 문서](/docs/webhooks/transcript)를 참고하세요.

### Summary Webhook

통화 받아쓰기 후 LLM 이 생성한 **구조화된 요약(Structured Output)** 이 완료되거나 실패했을 때 알림이 전송되며, 요약 결과 JSON 문자열이 포함됩니다.
**부가서비스 → 통화 받아쓰기** 와 **부가서비스 → 통화 요약** 이 모두 활성화되어 있어야 동작하는 유료 기능입니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Summary Webhook 문서](/docs/webhooks/summary)를 참고하세요.

### 관리번호 Webhook

[관리번호 발급 링크](/docs/api-reference/assignment-links)로 엔드유저가 본인인증을 마치고 070번호가 개통되면 `assignment.completed` 이벤트가 전송됩니다.
발급 결과를 폴링으로 확인할 필요가 없어집니다. **관리번호 추가** 애드온이 활성화된 계정에서 동작합니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [관리번호 Webhook 문서](/docs/webhooks/assignment)를 참고하세요.

### Agent 연결 상태 Webhook

Voice Agent SDK 의 상시 연결(Control WebSocket)이 **15초 이상 끊기면** `agent.disconnected`, 다시 연결되면 `agent.connected` 이벤트가 전송됩니다.
REST API `/v1/accounts/{accountId}/webhooks`로 **계정 레벨** 등록합니다.
자세한 내용은 [Agent 연결 상태 Webhook 문서](/docs/webhooks/agent)를 참고하세요.

## 네트워크 (IP 허용목록)

한국AI통신 플랫폼에서 고객 서버로 보내는 모든 발신 요청(Webhook 및 VoiceML XML fetch / status callback 포함)은 단일 고정 IP(HTTPS)에서 나갑니다.
방화벽 화이트리스트가 필요한 경우 **[네트워크 (IP 허용목록)](/docs/network)** 에서 허용할 IP를 확인해 주세요.

## 서명 검증

모든 요청에는 `X-Signature` 헤더가 포함됩니다. 프로덕션 환경에서는 반드시 서명을 검증하세요.

자세한 내용은 [서명 검증 가이드](/docs/webhooks/signature-verification)를 참고하세요.