인바운드 웹훅

인바운드 웹훅은 전화가 걸려 오면 발신번호와 수신번호를 내 서버로 보내고, 서버가 돌려준 값을 통화 시작 전에 동적 변수와 메타데이터로 넣어요. CRM이나 DB에 있는 고객 정보를 프롬프트에 넣을 때 가장 많이 쓰는 경로예요. 에이전트 설정의 인바운드 웹훅 URL 입력란

인바운드 웹훅 연결하기

수신 서버 만들기

아래 요청과 응답 형식대로 답하는 HTTPS 엔드포인트를 준비하세요. 예시는 서버 구현 예시에 있어요.

인바운드 웹훅 URL 넣기

에이전트 설정의 웹훅 설정을 열고 인바운드 웹훅 URL에 엔드포인트를 넣은 뒤 저장하세요. URL은 https://만 저장돼요. 이 응답이 동적 변수를 만드는 곳이라 URL 자체에는 동적 변수를 쓸 수 없어요.

프롬프트에 변수 넣기

응답의 dynamic_variables 키와 같은 이름으로 프롬프트에 {{변수명}}을 넣으세요. 통화가 시작될 때 값으로 바뀌어요.

실제 통화로 확인하기

curl로 먼저 시험한 뒤 실제 통화를 한 통 걸어 변수가 제대로 들어갔는지 보세요.

요청과 응답

전화가 걸려 오면 vox.ai가 아래 JSON 본문으로 POST 요청을 보내요. 본문 형식은 고정이에요.

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

타임아웃: 한 번에 10초까지 기다리고 2번까지 시도해요. 그동안 발신자는 벨소리를 들어요. 합쳐 약 20초를 넘기면 전화가 끊길 수 있으니 8초 안에 응답하세요.
재시도: 실패하면 짧은 간격으로 한 번 다시 보내요. 다시 보내는 요청도 같은 (call_from, call_to)로 오므로 중복을 가려야 하면 서버에서 자체 키로 처리하세요.
실패하면: 응답 오류나 빠른 실패는 동적 변수 없이 통화를 이어가니 프롬프트에 변수가 비었을 때의 분기를 두세요. 두 번 모두 시간이 초과되면 전화가 연결되지 않을 수 있어요.

응답 JSON은 아래 구조를 따라야 해요. dynamic_variables의 키가 프롬프트의 {{변수명}}과 같으면 자동으로 바뀌어요.

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

dynamic_variables: 키와 값의 쌍이에요. 값은 문자열, 숫자, 불리언만 돼요. 배열이나 객체 같은 중첩 값을 다루는 방법은 동적 변수 작성 문법에 있어요.
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"]},
        }
    }

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 서명 헤더가 붙어요. 엔드포인트에서 요청이 vox.ai에서 왔는지 검증할 수 있어요. 기본값은 꺼짐이고, 꺼 두면 서명 없이 보내요. 인바운드 웹훅 서명 스위치와 워크스페이스 서명 키 안내

헤더	설명	예시
`X-Webhook-Timestamp`	서명을 만든 시점. Unix 초	`1738900000`
`X-Webhook-Signature`	HMAC-SHA256 서명	`sha256=a1b2c3...`

서명 키와 검증 방식은 워크스페이스 단위 웹훅의 HMAC-SHA256 서명과 같아요. "{timestamp}.{원본 요청 본문}"에 서명하므로 받은 원본 본문 그대로 검증하세요. 통화 데이터 웹훅 서명을 이미 검증하고 있다면 같은 코드를 그대로 쓰면 돼요.

서명 키: 대시보드 설정 > 웹훅에서 발급하는 워크스페이스 웹훅 서명 키를 함께 써요. 에이전트별 키는 없어요.
키가 없을 때: 워크스페이스에 서명 키가 없으면 켜 두어도 서명 없이 보내요. 켜기 전에 키를 먼저 발급하세요.

엔드포인트 쪽 추가 방어

서명 검증과 별도로 엔드포인트에서 다음을 적용할 수 있어요.

HTTPS 전용: 인바운드 웹훅 URL은 https://만 저장돼요.
자체 토큰: URL 경로나 쿼리에 비밀 토큰을 넣고 서버에서 검증하세요. 예: https://api.example.com/webhook/inbound?token=YOUR_SECRET_TOKEN
요청 검증: call_from이 E.164나 한국 휴대전화 형식인지, call_to가 자사에 등록된 수신번호인지 확인하세요.

방화벽 화이트리스트 정책이 필요하면 vox.ai에 따로 문의해 주세요.

연결 확인

본문 형식이 고정이라 엔드포인트는 curl로 직접 시험할 수 있어요.

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 헤더 자동 주입과 SIP 연동에 있어요.

예외 상황

상황	동작
타임아웃	두 번 모두 시간이 초과되면 전화가 연결되지 않을 수 있어요. 8초 안에 응답하세요
실패	재시도 뒤에도 실패하면 `dynamic_variables` 없이 통화를 진행해요. 프롬프트의 `{{변수명}}`은 그대로 LLM에 전달돼요
SIP 헤더와 웹훅 응답의 키가 겹침	웹훅 응답 값이 먼저예요
응답 JSON 형식 오류	동적 변수 없이 통화를 진행해요. 다시 보내지 않아요
빈 `dynamic_variables` 반환	정상 응답으로 보고 변수 없이 통화를 진행해요

시작하기

구축

배포

발신

모니터링

설정

정책