Webhook 개요
ClawOps Webhook 전체 가이드 — Status Callback, Message, Recording, Transcript, Summary Webhook 의 페이로드와 HMAC-SHA256 서명 검증 방법.
개요
ClawOps는 통화 및 메시지 관련 이벤트를 실시간으로 알려주는 알림을 제공합니다.
이벤트가 발생하면 설정된 URL로 HTTP POST 요청이 전송되며, 서버는 200 또는 204로 응답합니다.
종류
Status Callback
통화 상태가 변경될 때마다 (ringing → answered → completed, 또는 busy/rejected) 이벤트가 전송됩니다.
- 발신(outbound):
calls.create()의status_callback파라미터로 통화별 설정합니다. - 수신(inbound): 전화번호 설정의
status_callback(대시보드 "수신 통화 상태 webhook" 또는 번호 API)에 번호별로 미리 등록합니다.
자세한 내용은 Status Callback 문서를 참고하세요.
Message Webhook
문자 메시지(SMS) 관련 이벤트(발송 완료, 실패, 수신)가 발생하면 알림이 전송됩니다.
REST API /v1/accounts/{accountId}/webhooks로 계정 레벨 등록합니다.
자세한 내용은 Message Webhook 문서를 참고하세요.
Recording Webhook
통화 녹음 파일이 GCS 에 업로드되거나 업로드에 실패했을 때 알림이 전송되며, API key 인증으로 다운로드 가능한 RecordingUrl 이 포함됩니다.
부가서비스 → 통화 녹음 이 활성화되어 있어야 동작합니다.
REST API /v1/accounts/{accountId}/webhooks로 계정 레벨 등록합니다.
자세한 내용은 Recording Webhook 문서를 참고하세요.
Transcript Webhook
통화 전사(STT)가 완료되거나 실패했을 때 알림이 전송되며, 전사 결과 JSON의 GCS 서명 URL이 포함됩니다.
부가서비스 → 통화 받아쓰기 를 활성화해야 동작하는 유료 기능입니다.
REST API /v1/accounts/{accountId}/webhooks로 계정 레벨 등록합니다.
자세한 내용은 Transcript Webhook 문서를 참고하세요.
Summary Webhook
통화 받아쓰기 후 LLM 이 생성한 구조화된 요약(Structured Output) 이 완료되거나 실패했을 때 알림이 전송되며, 요약 결과 JSON 문자열이 포함됩니다.
부가서비스 → 통화 받아쓰기 와 부가서비스 → 통화 요약 이 모두 활성화되어 있어야 동작하는 유료 기능입니다.
REST API /v1/accounts/{accountId}/webhooks로 계정 레벨 등록합니다.
자세한 내용은 Summary Webhook 문서를 참고하세요.
Agent 연결 상태 Webhook
Voice Agent SDK 의 상시 연결(Control WebSocket)이 15초 이상 끊기면 agent.disconnected, 다시 연결되면 agent.connected 이벤트가 전송됩니다.
REST API /v1/accounts/{accountId}/webhooks로 계정 레벨 등록합니다.
자세한 내용은 Agent 연결 상태 Webhook 문서를 참고하세요.
네트워크 (IP 허용목록)
ClawOps 플랫폼에서 고객 서버로 보내는 모든 발신 요청(Webhook 및 VoiceML XML fetch / status callback 포함)은 단일 고정 IP(HTTPS)에서 나갑니다. 방화벽 화이트리스트가 필요한 경우 네트워크 (IP 허용목록) 에서 허용할 IP를 확인해 주세요.
서명 검증
모든 요청에는 X-Signature 헤더가 포함됩니다. 프로덕션 환경에서는 반드시 서명을 검증하세요.
자세한 내용은 서명 검증 가이드를 참고하세요.