웹훅 엔드포인트

엔드포인트별 시크릿 및 이벤트 필터를 사용하여 여러 웹훅 URL을 관리합니다.

엔드포인트 기반 웹훅 시스템을 사용하면 조직별로 여러 대상을 등록할 수 있으며, 각 대상에는 고유한 시크릿, 상태, 이벤트 유형 하위 집합에 대한 구독이 있습니다. 이는 모든 신규 통합에 권장되는 모델입니다.

하위 호환성을 위해 유지되지만 조직당 하나의 URL만 지원하는 레거시 단일 URL 웹훅과 비교하세요.

엔드포인트#

엔드포인트 객체#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

유효한 이벤트 유형#

events는 다음의 정확한 집합을 기준으로 검증됩니다. 목록에 없는 값은 400을 반환합니다. 각 유형의 페이로드 형식은 이벤트 카탈로그를 참조하세요.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received(예약됨, 아직 발생하지 않음)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated에는 에이전트 컨텍스트가 없으며 조직 전체 엔드포인트에만 전송됩니다.

voice.ready 및 voice.failed는 명시적으로 선택할 수 없습니다. 이를 수신하려면 events: []로 조직 전체 엔드포인트를 생성하세요. 빈 이벤트 목록은 명시적으로 선택해야 하는 telephony.turn 및 web.turn을 제외한 모든 지원 이벤트를 수신합니다.

엔드포인트 상태#

• active — 전송이 정상적으로 이루어집니다.
• disabled — PATCH를 통해 수동으로 일시 중지된 상태입니다. 요청이 전송되지 않습니다. ThunderPhone은 disabled 엔드포인트의 상태를 변경하지 않으며, active로 다시 전환할지는 항상 사용자가 결정합니다.
• failing — 엔드포인트로의 전송이 2xx 응답을 한 번도 받지 못한 채 전체 재시도 일정(24시간 동안 8회 시도)을 모두 소진하면 자동으로 설정됩니다. 실패 상태의 엔드포인트에는 추가 트래픽이 전송되지 않습니다. 이 경우 조직의 소유자와 관리자에게 이메일을 보내며, 대시보드에는 일시 중지된 엔드포인트와 함께 다시 활성화 버튼이 표시됩니다. 엔드포인트를 수정한 후 상태를 PATCH로 다시 active로 변경하면, 재시도 일정이 아직 만료되지 않은 전송은 중단된 지점부터 재개됩니다.

엔드포인트 목록 조회#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

엔드포인트 객체 배열을 반환합니다. ?agent_id=42를 전달하면 해당 에이전트로 범위가 지정된 엔드포인트만 반환합니다.

에이전트 범위 엔드포인트#

조직 전체 엔드포인트는 일치하는 모든 이벤트를 수신합니다. agent_id가 있는 엔드포인트는 해당 에이전트가 처리한 통화에 대한 일치 이벤트만 수신합니다. alert.triggered처럼 에이전트 컨텍스트가 없는 이벤트는 해당 엔드포인트에 도달하지 않습니다. 이러한 엔드포인트는 에이전트 빌더의 웹훅 섹션에서도 생성하고 관리할 수 있습니다.

엔드포인트 만들기#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

요청 필드#

엔드포인트 객체와 원시 서명 키(48자 16진수 문자열)가 포함된 추가 최상위 secret 필드를 포함하여 201 Created를 반환합니다.

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

엔드포인트 업데이트#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

업데이트된 엔드포인트 객체와 함께 200 OK를 반환합니다.

서명 시크릿 교체#

엔드포인트의 서명 시크릿을 교체합니다. 예를 들어 시크릿을 분실했거나 유출되었을 수 있는 경우에 사용합니다. 에이전트 범위 엔드포인트의 경우 대시보드에서도 사용할 수 있습니다. 에이전트의 웹훅 섹션을 열고 엔드포인트에서 시크릿 재생성을 선택합니다. 조직 전체 엔드포인트는 API를 통해 교체합니다.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 OK를 반환합니다.

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

테스트 전송 보내기#

표준 전송 파이프라인을 사용하여 하나의 엔드포인트로 합성 webhook.test 이벤트를 전송합니다. 여기에는 정규 JSON 직렬화, 두 서명 헤더, 전송 기록 및 재시도 관리가 포함됩니다. 테스트는 events 필터와 관계없이 선택한 엔드포인트를 대상으로 합니다.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

엔드포인트는 다음과 같은 엔벨로프를 수신합니다.

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

대상에서 오류를 반환하더라도 API는 첫 번째 시도 후 200 OK를 반환합니다. 전송 결과는 success, status, response_code, error를 확인하십시오.

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test는 합성 이벤트이므로 엔드포인트의 events 구독에 추가할 수 없습니다. 첫 번째 시도가 실패하면 ThunderPhone은 약 1분 후 한 번 재시도한 다음 중지합니다. 이후 전송은 전송 디버깅에서 status: "failed"로 표시됩니다. 테스트 전송은 엔드포인트를 failing 상태로 표시하지 않습니다.

실제 이벤트 형태에 대한 트리거를 구성하려면 선택 사항인 event_type을 전달하십시오. 전송은 계속 합성 이벤트이며 "sample": true를 포함합니다. 통화 관련 샘플은 call_id: 0 및 agent_id: 0을 사용합니다.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type은 유효한 이벤트 유형의 모든 값을 허용합니다. 생략하면 일반 webhook.test 동작이 유지됩니다.

엔드포인트 삭제하기#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content를 반환합니다. URL로의 전송은 즉시 중지되며, 진행 중인 재시도는 중단됩니다.

전송 디버깅#

웹훅이 전송되지 않았다고 결론 내리기 전에 GET /v1/developer/webhook-deliveries를 확인하십시오. 이 API는 통화 ID, URL 오리진, HTTP 상태, 시도 횟수, 허용 목록에 포함된 실패 범주 및 다음 재시도 시간을 포함하여 두 웹훅 시스템의 최근 시도를 보여 줍니다. 이벤트 페이로드, 트랜스크립트, 저장된 오류 텍스트, 응답 본문 또는 URL 경로는 반환하지 않습니다.

에이전트 → 에이전트 선택 → 웹훅 → 최근 전송에서도 동일한 최근 기록을 확인할 수 있습니다. 행에는 엔드포인트 레이블과 최신 시도에 사용된 URL 오리진이 표시됩니다. 이는 변경 불가능한 감사 로그가 아닌 운영 상태이므로 엔드포인트를 삭제하면 해당 전송 행도 삭제됩니다.

n8n 404의 경우 먼저 워크플로가 활성 상태이고 POST를 허용하며 테스트 URL이 아닌 프로덕션 웹훅 URL을 사용하는지 확인하십시오. 401 또는 403은 인증 또는 서명 검증 문제를 나타냅니다. 시간 초과는 대상 지연 시간 또는 가용성 문제를 나타내며, TLS 오류는 인증서 체인, 호스트 이름 또는 만료 문제를 나타냅니다.

관련 항목#