> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.
# 인바운드 웹훅
> 걸려온 통화의 발신·수신 번호를 기반으로 사용자가 운영하는 서버에서 동적 변수와 메타데이터를 반환받는 통합 경로입니다.
# 인바운드 웹훅
걸려온 통화의 발신·수신 번호를 기반으로, 사용자가 운영하는 서버에서 동적 변수와 메타데이터를 반환하는 방식입니다. CRM/DB에 있는 고객 정보를 프롬프트에 녹일 때 가장 많이 쓰이는 경로입니다.
이 페이지는 [동적 변수](/docs/build/variables/dynamic-variables)의 **인바운드 웹훅 주입 경로**를 다룹니다.
## 웹훅 URL 설정
에이전트 빌드 화면의 **웹훅 설정** 아코디언을 열면 **인바운드 웹훅 URL** 필드가 있습니다. 여기에 사용자가 운영하는 엔드포인트를 입력하고 저장합니다.
* placeholder: `https://api.example.com/webhook/inbound`
* 설명: *"통화 시작 전 발신 번호를 기반으로 동적 변수(고객명, 상품명 등)를 프롬프트에 주입합니다."*
## 요청 페이로드
인바운드 통화가 들어오면 vox.ai가 다음 JSON 바디로 **POST** 요청을 보냅니다. 페이로드 형식은 **고정**입니다.
```json theme={null}
{
"call_from": "01012345678",
"call_to": "0212345678"
}
```
* **타임아웃**: **10초** 안에 응답해야 통화가 정시 시작됩니다
* **재시도**: 실패 시 짧은 간격으로 최대 2회 재시도합니다. 재시도 호출은 같은 `(call_from, call_to)` 로 들어오므로 중복 감지가 필요하면 서버에서 자체 키로 처리하세요
* **실패 시 동작**: 재시도 후에도 실패하면 동적 변수 없이 통화가 이어집니다 — 프롬프트에서 변수 누락을 가정한 분기 처리를 두는 것이 안전합니다
## 응답 스키마
응답 JSON은 다음 구조를 따라야 합니다. `dynamic_variables`의 키를 프롬프트의 `{{변수명}}`과 일치시키면 자동으로 치환됩니다.
```json theme={null}
{
"call_inbound": {
"dynamic_variables": {
"user_name": "김철수",
"product_name": "아이폰 16 프로"
},
"metadata": {
"user_id": "cust_12345"
}
}
}
```
* **`dynamic_variables`** — 키-값 쌍. **값은 문자열·숫자·불리언만 지원**합니다. 중첩 값(배열·객체) 의 처리 방식과 워크어라운드는 [동적 변수 작성 문법 Warning](/docs/build/variables/dynamic-variables#작성-문법) 을 참고하세요.
* **`metadata`** — 에이전트 프롬프트에는 주입되지 않고, 이 통화의 메타데이터로 저장됩니다. 나중에 [통화 데이터 웹훅](/docs/build/security/webhooks)의 `call.metadata` 로 그대로 전달되므로, 내부 고객 ID 처럼 다운스트림에서 필요한 식별자를 실어 보낼 수 있습니다.
## 서버 구현 예시
```python webhook_server.py theme={null}
from fastapi import FastAPI
app = FastAPI()
@app.post("/check-caller")
async def check_caller(post_body: dict):
call_from = post_body.get("call_from")
customer = await db.users.find_by_phone(call_from) # CRM 조회
if not customer:
return {"call_inbound": {"dynamic_variables": {}}}
return {
"call_inbound": {
"dynamic_variables": {
"customer_name": customer["name"],
"tier": customer["tier"],
},
"metadata": {"user_id": customer["id"]},
}
}
```
```javascript webhook_server.js theme={null}
const express = require("express");
const app = express();
app.use(express.json());
app.post("/check-caller", async (req, res) => {
const { call_from } = req.body;
const customer = await db.users.findByPhone(call_from); // CRM 조회
if (!customer) {
return res.json({ call_inbound: { dynamic_variables: {} } });
}
res.json({
call_inbound: {
dynamic_variables: {
customer_name: customer.name,
tier: customer.tier,
},
metadata: { user_id: customer.id },
},
});
});
```
## 보안
### HMAC 서명 검증 (선택)
에이전트 설정의 **웹훅 설정** 섹션에서 **인바운드 웹훅 서명** 토글을 켜면, 인바운드 웹훅 요청에 HMAC-SHA256 서명 헤더가 포함됩니다. endpoint 가 이 요청이 vox.ai 에서 온 것인지 검증할 수 있습니다. 기본값은 꺼짐이며, 꺼진 상태의 요청은 기존과 동일하게 서명 없이 전송됩니다.
| 헤더 | 설명 | 예시 |
| --------------------- | ------------------ | ------------------ |
| `X-Webhook-Timestamp` | 서명 생성 시점 (Unix, 초) | `1738900000` |
| `X-Webhook-Signature` | HMAC-SHA256 서명 | `sha256=a1b2c3...` |
서명 키와 검증 방식은 [워크스페이스 단위 웹훅의 HMAC-SHA256 서명](/docs/operate/monitor/webhooks/organization#hmac-sha256-서명)과 동일합니다 — `"{timestamp}.{원본 요청 본문}"` 을 서명하며, 받은 원본 본문 그대로 검증해야 합니다. 통화 데이터 웹훅 서명을 이미 검증하고 있다면 같은 검증 코드를 그대로 재사용하세요.
* 서명 키는 대시보드 **설정 > 웹훅** 에서 발급하는 **워크스페이스 웹훅 서명 키**를 함께 사용합니다. 에이전트별 키는 없습니다.
* 워크스페이스에 서명 키가 없으면 토글을 켜도 서명 없이 전송됩니다. 토글을 켜기 전에 키를 먼저 발급하세요.
### endpoint 쪽 추가 방어
서명 검증과 별개로, 사용자 endpoint 쪽에서 다음을 적용할 수 있습니다.
* **HTTPS 전용** — 인바운드 웹훅 URL 은 `https://` 만 허용됩니다 (`http://` 는 저장 불가)
* **자체 토큰** — URL path 또는 query 에 secret token 을 포함시켜 서버에서 검증합니다. 예: `https://api.example.com/webhook/inbound?token={{시크릿}}`
* **요청 검증** — `call_from` 형식이 E.164 또는 한국 휴대전화 패턴인지, `call_to` 가 자사가 등록한 수신 번호인지 확인합니다
방화벽 화이트리스트 정책이 필요한 경우 vox.ai 측에 별도로 문의해 주세요.
## 테스트
페이로드 형식이 고정이므로 사용자 endpoint 자체는 curl 로 직접 시뮬레이션할 수 있습니다.
```bash theme={null}
curl -X POST 'https://api.example.com/webhook/inbound' \
-H 'Content-Type: application/json' \
-d '{"call_from": "01012345678", "call_to": "0212345678"}'
```
위 요청에 [응답 스키마](#응답-스키마) 형식대로 200 응답이 돌아오는지 먼저 확인한 다음, 실제 통화를 한 통 걸어 LLM 에 변수가 정상 주입됐는지 검수하세요.
## 보조 수단 — SIP 헤더
SIP 트렁킹으로 인바운드 통화를 받는 경우, PBX가 `X-`로 시작하는 커스텀 헤더에 고객 정보를 실어 보내면 **웹훅 서버 없이도** 자동으로 동적 변수로 주입됩니다. 웹훅과 동시에 사용할 수 있습니다 (충돌 시 우선순위는 [예외 상황](#예외-상황) 참고). 자세한 내용은 [시스템 변수 > SIP 헤더로 동적 변수 자동 주입](/docs/build/variables/system-variables#sip-헤더로-동적-변수-자동-주입)과 [SIP 트렁킹 가이드](/docs/operate/deploy/sip-telephony)를 참고하세요.
## 예외 상황
| 상황 | 동작 |
| ------------------------ | ----------------------------------------------------------------------------- |
| 타임아웃 / 실패 | 재시도 2회 후에도 실패하면 `dynamic_variables` 없이 통화 진행 — 프롬프트의 `{{변수명}}` 은 그대로 LLM 에 전달 |
| SIP 헤더와 웹훅 응답 키 충돌 | 웹훅 응답 값이 우선 |
| 응답 JSON 형식 오류 | 동적 변수 없이 통화 진행 (재시도 없음) |
| 빈 `dynamic_variables` 반환 | 정상 응답으로 간주, 변수 없이 통화 진행 |
## 관련 문서
* [동적 변수](/docs/build/variables/dynamic-variables) — 인바운드 웹훅 외 4가지 주입 경로 (단건/대량 발신, SDK, 테스트 프리셋)
* [시스템 변수](/docs/build/variables/system-variables) — 자동 주입 변수와 SIP 헤더 자동 주입
* [SIP 트렁킹](/docs/operate/deploy/sip-telephony)
* [통화 데이터 웹훅](/docs/build/security/webhooks)
***
인바운드 웹훅, inbound webhook, 발신 번호 인식, 고객 정보 주입, CRM 연동, X-헤더, SIP 헤더, dynamic\_variables, 통화 시작 웹훅, call\_from, call\_to, webhook 응답 스키마, 화이트리스트, 재시도 정책, webhook 인증, webhook 보안, HMAC 서명, 서명 검증, X-Webhook-Signature, 인바운드 웹훅 서명