인바운드 웹훅

인바운드 웹훅 연결하기

요청과 응답

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

• 타임아웃: 한 번에 10초까지 기다리고 2번까지 시도해요. 그동안 발신자는 벨소리를 들어요. 합쳐 약 20초 동안 기다리던 발신자가 전화를 끊을 수 있으니 8초 안에 응답하세요.
• 재시도: 실패하면 짧은 간격으로 한 번 다시 보내요. 다시 보내는 요청도 같은 (call_from, call_to)로 오므로 중복을 가려야 하면 서버에서 자체 키로 처리하세요.
• 실패하면: 응답 오류든 시간 초과든 두 번 모두 실패하면 동적 변수 없이 통화를 이어가요. 프롬프트에 변수가 비었을 때의 분기를 두세요. 두 번 모두 시간이 초과되면 발신자는 약 20초 동안 벨소리만 듣기 때문에 그 사이 전화를 끊을 수 있어요.
• 차단 번호가 먼저: 차단 번호 규칙이 웹훅보다 먼저 적용돼요. 차단된 통화는 웹훅이 호출되지 않아요.
• 응답 코드: 2xx가 아닌 응답은 한 번 다시 보내요. 리다이렉트는 따라가지 않아요.
• 덮어쓸 수 없는 변수: current_time, call_id, agent_id, call_from, call_to는 응답으로 덮어쓸 수 없어요.

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

• dynamic_variables: 키와 값의 쌍이에요. 값은 문자열, 숫자, 불리언만 돼요. 배열이나 객체 같은 중첩 값을 다루는 방법은 동적 변수 작성 문법에 있어요.
• metadata: 프롬프트에는 들어가지 않고 이 통화의 메타데이터로 저장돼요. 나중에 통화 데이터 웹훅의 call.metadata로 그대로 가므로 내부 고객 ID처럼 다음 시스템에서 필요한 식별자를 실어 보낼 수 있어요.

통화 거절하기

{
  "call_inbound": {
    "reject": true
  }
}

• 발신자: 에이전트가 받기 전에 통화가 연결되지 않고 끝나요.
• 통화 기록: 연결 종료 사유가 웹훅 거절(inbound_webhook_reject)로 남아요.
• 요금: 거절된 통화는 요금이 부과되지 않아요.
• 응답이 없으면: 웹훅 응답이 없거나 실패하면 통화는 거절되지 않고 연결돼요.
• 적용 조건: reject는 불리언 true일 때만 적용돼요. "true" 같은 문자열은 거절로 보지 않아요.

서버 구현 예시

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 서명 검증 (선택)

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

엔드포인트 쪽 추가 방어

• HTTPS 전용: 인바운드 웹훅 URL은 https://만 저장돼요.
• 자체 토큰: URL 경로나 쿼리에 비밀 토큰을 넣고 서버에서 검증하세요. 예: https://api.example.com/webhook/inbound?token=YOUR_SECRET_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 헤더로 넘기기

예외 상황

관련 문서

• 동적 변수: 인바운드 웹훅 말고 다른 네 가지 주입 경로(전화, 대량 발신, SDK, 테스트 프리셋)
• 시스템 변수: 자동으로 들어가는 변수와 SIP 헤더 자동 주입
• SIP 연동: SIP 트렁크와 PBX 연결하기
• 웹훅 개요: 통화 데이터 웹훅