> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # 이벤트 카탈로그 > ThunderPhone이 전송하는 모든 웹훅 이벤트 유형입니다. 모든 웹훅 본문에는 이 페이지의 이벤트 유형 중 하나를 값으로 갖는 `type` 필드가 있습니다. [엔드포인트](/ko/webhooks/endpoints)를 구독할 때 `events` 배열에는 원하는 이벤트 유형을 포함해야 합니다(모든 이벤트를 구독하려면 비워 둡니다). 이러한 이벤트는 두 가지 전달 방식으로 전송됩니다. * **엔드포인트 전달**은 항상 [재시도](/ko/webhooks/overview)가 적용되는 **비차단** 알림입니다. 모든 2xx로 응답합니다. 중복 제거에는 봉투의 `event_id`를 사용합니다. * **차단** 교환은 [레거시 단일 URL 웹훅](/ko/webhooks/overview)에서만 실행됩니다. [`telephony.incoming` / `web.incoming`](/ko/webhooks/call-incoming) 구성 요청(웹훅 모드 번호 및 위젯 키, 10초 제한 시간)과 웹훅 모드 [도구 디스패치](/ko/tools/overview)가 이에 해당합니다. 응답이 진행 중인 통화를 결정합니다. 아래 예제 페이로드는 전송 순서의 엔드포인트 봉투를 보여 줍니다(키는 `data`, `event_id`, `type` 순으로 알파벳순 정렬됨). 레거시 전달에는 `event_id` 없이 동일한 `data`가 포함됩니다. ## 통화 이벤트 ### `telephony.incoming` 수신 통화가 [전화번호](/api-reference/phone-numbers) 중 하나에 도달하면 전송됩니다. 엔드포인트 전송은 번호가 에이전트로 구성되었는지 또는 웹훅으로 구성되었는지와 관계없이 **모든** 수신 통화에 대해 전송되는 fire-and-forget 알림입니다. 에이전트가 할당되지 않은 번호는 레거시 웹훅에서 추가로 **차단형** 구성 요청을 수신합니다. 전체 요청/응답 스키마는 [`telephony.incoming` / `web.incoming`](/ko/webhooks/call-incoming)을 참조하세요. ```json theme={null} { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` ### `telephony.complete` 수신 또는 발신 전화 통화가 종료되면 전송됩니다. 비차단형입니다. 전체 트랜스크립트, 녹음 URL 및 청구 요약을 포함합니다. 페이로드 스키마는 [`telephony.complete` / `web.complete`](/ko/webhooks/call-complete)을 참조하세요. ### `telephony.tool` 전화 통화가 [함수 도구](/ko/tools/overview)를 호출한 후 전송됩니다. 비차단형 감사 알림입니다. 이 이벤트가 전송될 때 도구는 이미 실행되어 있으며, 기본 제공 도구, 지식 베이스 도구, 앱 연결 도구 또는 MCP 도구가 아닌 자체 함수 도구에 적용됩니다. ```json theme={null} { "data": { "arguments": { "date": "2026-04-21" }, "call_id": 987654321, "from_number": "+14155550199", "response": { "response": { "available_slots": ["9:00 AM", "2:00 PM"] }, "status": 200 }, "to_number": "+15551234567", "tool_name": "search_appointments" }, "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2", "type": "telephony.tool" } ``` `response`는 실행 결과입니다. 성공 시 `{"status": , "response": }`이고, 실패 시 `{"status": , "error": ""}`입니다. ### `web.incoming` [웹 위젯](/ko/widget/overview) 세션 또는 빌더 마이크 테스트 통화가 시작될 때 전송되는 `telephony.incoming`의 웹 채널 대응 이벤트입니다. 엔드포인트 전송은 모든 웹 세션에 대한 fire-and-forget 알림입니다. `mode="webhook"`의 공개 키는 레거시 웹훅에서 추가로 **차단형** 구성 요청을 수신합니다. 이 차단형 요청은 형태가 다르며(`origin_domain`, `publishable_key_prefix`, 전화번호 없음), 자세한 내용은 [`telephony.incoming` / `web.incoming`](/ko/webhooks/call-incoming)을 참조하세요. ```json theme={null} { "data": { "call_id": 987654322, "from_number": "web", "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2", "to_number": "+15551234567" }, "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d", "type": "web.incoming" } ``` `from_number`는 항상 리터럴 `"web"`입니다. 웹훅 모드 위젯 세션에서는 `to_number`가 비어 있습니다. 세션의 에이전트 번호는 구성 후 할당됩니다. 빌더 마이크 테스트 통화에서는 `origin_domain` 및 `publishable_key_prefix`가 비어 있습니다. ### `web.complete` 웹 위젯 통화(`direction: "web"`) 및 빌더 마이크 테스트 통화(`direction: "test"`)를 처리하는 `telephony.complete`의 웹 채널 대응 이벤트입니다. 비차단형입니다. [`telephony.complete`](/ko/webhooks/call-complete)과 동일한 페이로드 형태에 `origin_domain`이 추가되며, `from_number`는 `"web"`으로 설정됩니다. 레거시 단일 URL 웹훅에서 빌더 마이크 테스트 통화는 역사적으로 `telephony.complete`로 보고됩니다. 해당 위치에서는 `direction: "web"` 통화만 `web.complete` 유형을 사용합니다. 엔드포인트 시스템은 웹 통화와 테스트 통화를 모두 `web.*`에 매핑합니다. 과거 페이로드에는 레거시 `direction` 값인 `widget` 또는 `mic`가 포함될 수 있습니다. ### `web.tool` `telephony.tool`의 웹 채널 대응 이벤트입니다. `data`에는 `from_number` / `to_number` 대신 `origin_domain`이 포함됩니다. *** ## 품질 이벤트 ### `call.graded` 통화의 [AI 평가 실행](/api-reference/calls#ai-call-grading)이 완료될 때마다 전송됩니다. 차단하지 않습니다. ```json theme={null} { "data": { "call_id": 987654321, "grade": { "call_outcome": "success", "created_at": "2026-04-20T18:25:11.002Z", "detected_issues": [], "graded_at": "2026-04-20T18:25:11.002Z", "grader_model": "heuristic-v1", "id": 5512, "score": 92, "status": "completed", "summary": "Caller asked about their policy and got a full answer…" } }, "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "type": "call.graded" } ``` | 필드 | 유형 | 설명 | | ------------------------------------- | --------------- | ---------------------------------------------------- | | `grade.id` | integer | 평가 ID | | `grade.score` | integer \| null | 0–100 | | `grade.call_outcome` | string | `success`, `failure`, `unknown` 또는 `no_conversation` | | `grade.summary` | string | 한 단락 요약 | | `grade.detected_issues` | array | 평가기가 발견한 이슈 문자열 | | `grade.status` | string | 항상 `completed` — 완료된 실행만 전송됩니다 | | `grade.grader_model` | string | 결과를 생성한 평가기(예: `heuristic-v1`) | | `grade.graded_at`, `grade.created_at` | timestamp | | 하나의 통화는 두 번 이상 평가될 수 있습니다. 녹음 파일을 사용할 수 있게 되면 빠른 휴리스틱 평가 뒤에 전체 모델 평가가 이어지는 경우가 많으며, 수동 재평가도 가능합니다. 완료된 각 실행은 자체 `call.graded` 이벤트를 전송합니다. 가장 최근의 `graded_at`을 권위 있는 값으로 처리하십시오. ### `issue.reported` [이슈 보고서](/api-reference/issue-reports)가 생성될 때 전송됩니다. 대시보드에서 사용자가 제출한 경우(`source: "user"`) 또는 통화 평가에 의해 자동으로 생성된 경우(`source: "system"`)가 해당합니다. 차단하지 않습니다. ```json theme={null} { "data": { "call_id": 987654321, "issue_report": { "created_at": "2026-04-20T18:25:11.002Z", "description": "Five-second silence before responding to the main question.", "id": 4321, "severity": "warning", "source": "system", "status": "open", "title": "Agent paused too long" } }, "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "type": "issue.reported" } ``` | 필드 | 유형 | 설명 | | ----------------------- | ------ | ------------------------------------- | | `issue_report.severity` | string | `critical`, `warning` 또는 `info` | | `issue_report.status` | string | `open` 또는 `resolved` | | `issue_report.source` | string | `user`(대시보드에서 제출) 또는 `system`(평가로 생성) | 통화를 재평가하면 시스템에서 생성한 이슈 보고서가 다시 생성되며, 재생성된 보고서에 대해 `issue.reported`가 다시 전송됩니다. 근본 문제당 하나의 알림만 받으려면 `call_id` + `title`을 기준으로 중복을 제거하십시오. *** ## 테스트 통화 이벤트 ### `test-call.completed` [테스트 통화 실행](/api-reference/test-calls#test-call-run-object)이 종료 상태인 `completed` 또는 `failed`에 도달하면 전송됩니다. 시작 시 실패하여 통화를 생성하지 못한 실행도 포함됩니다. 차단하지 않습니다. 일괄 CI 실행을 채팅 및 알림 시스템에 연결하는 데 유용합니다. ```json theme={null} { "data": { "test_call_run": { "call_id": 987654321, "completed_at": "2026-04-20T18:25:04.822Z", "error_message": "", "id": 7110, "status": "completed", "target_id": 12, "target_type": "agent" } }, "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "type": "test-call.completed" } ``` | 필드 | 유형 | 설명 | | ----------------------------- | --------------- | -------------------------------------------- | | `test_call_run.target_type` | string | `agent` 또는 `phone_number` | | `test_call_run.target_id` | integer | `target_type`에 해당하는 실행 대상 에이전트 ID 또는 전화번호 ID | | `test_call_run.status` | string | `completed` 또는 `failed` | | `test_call_run.call_id` | integer \| null | 통화가 시작되기 전에 실행이 실패한 경우 `null` | | `test_call_run.error_message` | string | 성공 시 비어 있음 | *** ## 알림 이벤트 ### `alert.triggered` **개발자 웹훅으로 전달** 채널이 활성화된 [알림 규칙](/ko/guides/alerts)이 임계값을 넘을 때 전송됩니다. 비차단 방식입니다. 규칙은 한 번 실행된 후 쿨다운을 준수하므로, 지속적인 위반은 쿨다운 기간당 하나의 이벤트를 생성합니다. ```json theme={null} { "data": { "comparator": "lt", "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d", "fired_at": "2026-04-20T18:00:00+00:00", "metric": "success_rate", "metric_value": 71.4, "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b", "rule_name": "Success rate below 80%", "threshold": 80.0, "window_hours": 24 }, "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a", "type": "alert.triggered" } ``` | 필드 | 유형 | 설명 | | ---------------------- | --------- | -------------------------------------------------------------------------------- | | `event_id` (`data` 내) | UUID | 알림 **실행** ID이며, 엔벨로프의 전달 `event_id`와는 다릅니다. | | `rule_id`, `rule_name` | UUID, 문자열 | 실행된 규칙입니다. | | `metric` | 문자열 | `success_rate`, `failure_rate`, `avg_score`, `call_volume` 또는 `suite_regression` | | `comparator` | 문자열 | `lt`, `lte`, `gt` 또는 `gte` | | `metric_value` | 숫자 | 규칙이 실행되었을 때 기간 내 측정항목 값입니다. | | `threshold` | 숫자 | 구성된 임계값입니다. | | `window_hours` | 정수 | 후행 평가 기간입니다. | | `fired_at` | 타임스탬프 | | 규칙, 측정항목, 쿨다운, 이메일 및 Slack 채널을 만드는 방법은 [알림 가이드](/ko/guides/alerts)를 참조하세요. *** ## 관련 항목 응답해야 하는 차단형 인바운드 통화 페이로드입니다. 통화 후 대화 기록 및 측정항목입니다. 이러한 이벤트의 일부에 URL을 구독시킵니다. `telephony.tool` / `web.tool` 이벤트가 생성되는 방식입니다.