​

인바운드 웹훅

​

웹훅 URL 설정

• placeholder: https://api.example.com/webhook/inbound
• 설명: “통화 시작 전 발신 번호를 기반으로 동적 변수(고객명, 상품명 등)를 프롬프트에 주입합니다.”

​

요청 페이로드

{
  "call_from": "01012345678",
  "call_to": "0212345678"
}

• 타임아웃: 10초 안에 응답해야 통화가 정시 시작됩니다
• 재시도: 실패 시 짧은 간격으로 최대 2회 재시도합니다. 재시도 호출은 같은 (call_from, call_to) 로 들어오므로 중복 감지가 필요하면 서버에서 자체 키로 처리하세요
• 실패 시 동작: 재시도 후에도 실패하면 동적 변수 없이 통화가 이어집니다 — 프롬프트에서 변수 누락을 가정한 분기 처리를 두는 것이 안전합니다

​

응답 스키마

{
  "call_inbound": {
    "dynamic_variables": {
      "user_name": "김철수",
      "product_name": "아이폰 16 프로"
    },
    "metadata": {
      "user_id": "cust_12345"
    }
  }
}

• dynamic_variables — 키-값 쌍. 값은 문자열·숫자·불리언만 지원합니다. 중첩 값(배열·객체) 의 처리 방식과 워크어라운드는 동적 변수 작성 문법 Warning 을 참고하세요.
• metadata — 에이전트 프롬프트에는 주입되지 않고, 이 통화의 메타데이터로 저장됩니다. 나중에 통화 데이터 웹훅의 call.metadata 로 그대로 전달되므로, 내부 고객 ID 처럼 다운스트림에서 필요한 식별자를 실어 보낼 수 있습니다.

​

서버 구현 예시

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"]},
        }
    }

​

보안

​

HMAC 서명 검증 (선택)

• 서명 키는 대시보드 설정 > 웹훅 에서 발급하는 워크스페이스 웹훅 서명 키를 함께 사용합니다. 에이전트별 키는 없습니다.
• 워크스페이스에 서명 키가 없으면 토글을 켜도 서명 없이 전송됩니다. 토글을 켜기 전에 키를 먼저 발급하세요.

​

endpoint 쪽 추가 방어

• HTTPS 전용 — 인바운드 웹훅 URL 은 https:// 만 허용됩니다 (http:// 는 저장 불가)
• 자체 토큰 — URL path 또는 query 에 secret token 을 포함시켜 서버에서 검증합니다. 예: https://api.example.com/webhook/inbound?token={{시크릿}}
• 요청 검증 — call_from 형식이 E.164 또는 한국 휴대전화 패턴인지, call_to 가 자사가 등록한 수신 번호인지 확인합니다

​

테스트

curl -X POST 'https://api.example.com/webhook/inbound' \
  -H 'Content-Type: application/json' \
  -d '{"call_from": "01012345678", "call_to": "0212345678"}'

​

보조 수단 — SIP 헤더

​

예외 상황

​

관련 문서

• 동적 변수 — 인바운드 웹훅 외 4가지 주입 경로 (단건/대량 발신, SDK, 테스트 프리셋)
• 시스템 변수 — 자동 주입 변수와 SIP 헤더 자동 주입
• SIP 트렁킹
• 통화 데이터 웹훅