POST 요청을 전송합니다. 예를 들어 수신 통화가 시작되거나, 통화가 종료되거나, 평가 실행이 완료되거나, 알림이 발생하는 경우입니다. 두 가지 전송 모델이 있습니다.
Webhook 엔드포인트(권장)
여러 URL, 엔드포인트별 시크릿, 엔드포인트별 이벤트 필터 및 자동 재시도를 제공합니다.
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints를 통해 관리합니다.단일 URL 레거시 webhook
조직당 하나의 URL입니다. 차단형 구성 교환을 포함한 통화 수명 주기 이벤트를 전달합니다.
GET/PUT /v1/webhook에서 관리합니다.telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool)는 추가로 레거시 단일 URL webhook으로도 전송됩니다. 레거시 URL과 일치하는 엔드포인트가 모두 있으면 두 경로에서 이벤트를 수신합니다. 차단형 동작(telephony.incoming / web.incoming 구성 교환 및 webhook 모드 도구 디스패치)은 레거시 경로에서만 제공됩니다. 모든 엔드포인트 전송은 응답을 기다리지 않는 알림입니다.
페이로드 형식
엔드포인트 전송은data, event_id, type을 포함하는 JSON 객체입니다.
event_id는 전송된 이벤트마다 고유합니다. 재시도 시에도 그리고 이벤트를 수신하는 모든 엔드포인트에서도 동일합니다. 이를 기준으로 중복을 제거하십시오.
레거시 단일 URL webhook은 동일한 type 및 data를 전송하지만 event_id는 포함하지 않습니다.
서명 검증
모든 요청은X-ThunderPhone-Signature 헤더에 원시 요청 본문에 대한 HMAC-SHA256 서명을 포함합니다. 서명 키는 엔드포인트의 secret이며(레거시 전송의 경우 조직 수준 웹훅 secret)입니다.
단계
- 파싱하기 전에 원시 요청 본문을 읽습니다.
hmac_sha256(secret, body).hexdigest()를 계산합니다.X-ThunderPhone-Signature헤더와 상수 시간으로 비교합니다.
전송 시맨틱
이 시맨틱은 엔드포인트 전송에 적용됩니다. 레거시 단일 URL 웹훅은 재시도 없이 한 번만 동기식으로 시도합니다.재시도
재시도
각 이벤트는 즉시 한 번 시도됩니다. 모든
2xx 응답은
전송을 확인합니다. 그 외 결과(2xx 이외 응답, 연결 오류,
타임아웃)가 발생하면 첫 번째 시도 후 1분, 5분, 30분, 2시간, 6시간,
12시간, 24시간에 재시도합니다. 즉, 24시간에 걸쳐 총 8회
시도합니다. 모든 시도가 실패하면 전송이 중단되고 엔드포인트는
웹훅 엔드포인트에서 status="failing"으로
표시됩니다. 페이로드가 영구적으로 수락되는 즉시 2xx를 반환하고,
비동기적으로 처리합니다.순서
순서
전송 순서는 최선의 노력으로 보장됩니다. 실제로는 이벤트가 발생한
순서대로 전송하지만, 실패 시 재시도로 인해 순서가 바뀔 수 있습니다.
항상
call_id / 객체 ID를 기준으로 중복을 제거하고 조정합니다.중복
중복
전송은 최소 한 번 보장됩니다. 확인하지 못한 응답 이후 재시도하면
이벤트가 중복될 수 있습니다. 모든 재시도에는 동일한
event_id가
포함되므로, 처리된 ID를 저장하고 반복 항목은 건너뜁니다. event_id는
엔드포인트 간에도 공유됩니다. 동일한 이벤트를 구독하는 두 엔드포인트는
같은 event_id를 수신합니다.타임아웃
타임아웃
엔드포인트 전송은 시도당 30초의 타임아웃이 적용됩니다. 레거시
경로에서는 실시간 통화 동작을 제어하는 차단 요청, 즉
telephony.incoming / web.incoming
구성 교환이 10초 후 타임아웃됩니다. 하지만 응답이 느리면 통화
수신이 지연되므로 몇 초 이내에 응답하는 것을 목표로 합니다. 웹훅 모드
도구 디스패치는 20초를 허용합니다.소스 IP
소스 IP
아웃바운드 웹훅은 ThunderPhone의 클라우드 IP 범위에서 발생합니다.
방화벽에 허용 목록이 필요한 경우 지원팀에 문의하면 현재 범위를
공유해 드립니다.
레거시 웹훅과 엔드포인트 기반 웹훅 중 선택
새 통합에서는 엔드포인트 기반 웹훅을 통해 이벤트를 소비해야 합니다.
통화 수신 시점에 동적으로 통화를 구성하거나 웹훅 모드 도구 디스패치를
사용하는 경우에만 레거시 URL을 유지하거나 추가합니다. 이러한 요청/응답
교환은 레거시 경로에서만 실행됩니다.
관련 항목
이벤트 카탈로그
모든 이벤트 유형 및 해당 페이로드입니다.
웹훅 엔드포인트
여러 엔드포인트, 이벤트 필터 및 시크릿을 관리합니다.
telephony.incoming / web.incoming
통화를 구성하기 위해 서버가 응답해야 하는 차단 요청입니다.
telephony.complete / web.complete
트랜스크립트, 녹음 및 측정항목을 포함한 통화 후 페이로드입니다.