
웹훅 연결하기
에이전트에 따로 넣은 URL이 있으면 그 URL이 먼저예요. 우선순위는 웹훅 개요에 있어요. 웹훅 URL은 통화가 시작될 때의 설정으로 고정되므로, 통화 중에 다른 에이전트로 전환되거나 설정을 바꾸면 다음 통화부터 적용돼요.1
웹훅 URL 넣기
대시보드 설정 > 웹훅에서 웹훅 URL에 수신 서버 주소를 넣고 저장을 누르세요. 더 받지 않으려면 삭제로 URL을 지우세요.
2
받을 이벤트 고르기
같은 화면의 이벤트 구독에서 받을 채팅, 문자, 대량 발신 이벤트를 켜고 저장을 누르세요. 이 이벤트들은 고른 것만 보내요.
3
서명 키 발급하고 보관하기
웹훅 서명 키 카드에서 발급을 누르세요. 키가 이미 있으면 같은 버튼이 다시 발급이에요. 키는 한 번만 보이니 서버 환경 변수에 저장하세요. 그 뒤에는
...b2f5처럼 마지막 4자리만 보여요.4
수신 서버에서 서명 검증하기
수신 서버에서 HMAC 서명을 검증하세요. 구현 예시는 서버에서 서명 검증하기에 있어요.
연결 확인
- 설정 > 웹훅에서 변경 사항을 저장한 뒤 테스트로 시험 요청을 보내세요.
- 수신 서버 로그에서
event_type이webhook.test인 요청이 도착했는지 확인하세요. - 서명 키를 발급했다면 받은 요청의 서명을 검증하고 성공하는지 확인하세요.
요청 검증하기
웹훅 요청은 IP 화이트리스트와 HMAC-SHA256 서명 두 가지로 확인해요. 둘 다 적용하세요.IP 화이트리스트
vox.ai 웹훅 요청은 고정 IP34.64.213.13에서 와요. 방화벽이나 리버스 프록시에서 이 IP만 허용하세요.
HMAC-SHA256 서명
서명 키를 발급해야 요청에 서명 헤더가 붙어요. 웹훅 요청에는 아래 헤더가 들어 있어요.
서명은 다음 규칙으로 계산하세요.
raw_request_body는 HTTP 요청에서 받은 원본 본문이에요. JSON을 파싱하거나 다시 직렬화하지 마세요. 공백, 키 순서, 이스케이프 방식이 바뀌면 서명이 달라져요.
에이전트의 인바운드 웹훅도 같은 서명 키와 검증 방식을 써요. 에이전트 설정의 인바운드 웹훅 서명으로 켜고, 기본값은 꺼짐이에요.
서명 키 관리
다시 발급하면 기존 키는 바로 무효가 돼요. 같은 카드의 삭제로 키를 지우면 웹훅 요청에서 서명 헤더가 빠져요.서버에서 서명 검증하기
아래 예시는 원본 본문으로 서명을 확인하고 5분 허용 시간을 적용해요. 서명 키는 환경 변수에 두고 코드에 직접 쓰지 마세요.문제가 생겼을 때
서명 검증이 계속 실패해요
서명 검증이 계속 실패해요
받은 원본 본문을 그대로 써서 검증하세요. 프레임워크 파서가 JSON을 먼저 읽으면 공백과 키 순서가 바뀌어 서명이 달라져요.
타임스탬프 검증에서 거부돼요
타임스탬프 검증에서 거부돼요
서버 시계를 맞추세요. 예시 코드는 타임스탬프가 현재 시각과 5분 넘게 차이 나는 요청을 거부해요.
키를 다시 발급한 뒤 검증이 실패해요
키를 다시 발급한 뒤 검증이 실패해요
다시 발급한 직후 새 키를 수신 서버에 배포하세요. 다시 발급하면 기존 키가 바로 무효가 되므로 배포가 늦으면 그사이 요청이 실패해요.