> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sajuapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹훅 상세 조회

<Info>
  **v1 Enterprise API (Coming Soon)**

  이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다.
  현재는 [v0 API](/api-reference/v0/overview)를 사용하세요.
</Info>

특정 웹훅의 상세 정보를 조회합니다. 최근 전송 기록과 실패 정보도 함께 반환됩니다.

***

## Path 파라미터

<ParamField path="id" type="string" required>
  조회할 웹훅의 ID입니다. `whk_` 접두사로 시작합니다.
</ParamField>

***

## Query 파라미터

<ParamField query="include_deliveries" type="boolean" default="false">
  최근 전송 기록을 포함할지 여부입니다. `true`면 최근 20건의 전송 기록이 포함됩니다.
</ParamField>

***

## Response

### 성공

웹훅 조회에 성공하면 Webhook 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명             |
| ----- | ---------------------- | -------------- |
| 401   | `authentication_error` | API 키가 유효하지 않음 |
| 404   | `not_found`            | 웹훅을 찾을 수 없음    |
| 429   | `rate_limited`         | 요청 한도 초과       |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sajuapi.dev/v1/webhooks/whk_abc123def456?include_deliveries=true" \
    -H "X-API-Key: bs_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sajuapi.dev/v1/webhooks/whk_abc123def456?include_deliveries=true',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  const webhook = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sajuapi.dev/v1/webhooks/whk_abc123def456',
      headers={'X-API-Key': 'bs_live_xxx'},
      params={'include_deliveries': 'true'}
  )

  webhook = response.json()
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "id": "whk_abc123def456",
  "url": "https://your-server.com/webhooks/saju",
  "events": ["fortune.generated", "profile.created", "daily.reset"],
  "description": "운세 생성 알림",
  "metadata": {
    "environment": "production",
    "team": "backend"
  },
  "active": true,
  "failure_count": 0,
  "last_triggered_at": "2025-01-16T08:30:00Z",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z",
  "deliveries": [
    {
      "id": "dlv_xyz789",
      "event_type": "fortune.generated",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 145,
      "attempted_at": "2025-01-16T08:30:00Z"
    },
    {
      "id": "dlv_abc456",
      "event_type": "profile.created",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 89,
      "attempted_at": "2025-01-16T07:15:00Z"
    },
    {
      "id": "dlv_def123",
      "event_type": "daily.reset",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 112,
      "attempted_at": "2025-01-16T00:00:00Z"
    }
  ],
  "statistics": {
    "total_deliveries": 156,
    "successful_deliveries": 154,
    "failed_deliveries": 2,
    "success_rate": 98.72,
    "average_response_time_ms": 125
  }
}
```

***

## Webhook 객체

| 필드                  | 타입      | 설명                                                |
| ------------------- | ------- | ------------------------------------------------- |
| `id`                | string  | 웹훅 ID입니다.                                         |
| `url`               | string  | 웹훅 수신 URL입니다.                                     |
| `events`            | array   | 구독 중인 이벤트 목록입니다.                                  |
| `description`       | string  | 웹훅 설명입니다.                                         |
| `metadata`          | object  | 메타데이터입니다.                                         |
| `active`            | boolean | 활성화 상태입니다.                                        |
| `failure_count`     | integer | 연속 실패 횟수입니다.                                      |
| `last_triggered_at` | string  | 마지막 트리거 시간입니다.                                    |
| `deliveries`        | array   | 최근 전송 기록입니다. `include_deliveries=true`일 때만 포함됩니다. |
| `statistics`        | object  | 전송 통계입니다.                                         |

***

## Delivery 객체

| 필드                 | 타입      | 설명                                                |
| ------------------ | ------- | ------------------------------------------------- |
| `id`               | string  | 전송 ID입니다.                                         |
| `event_type`       | string  | 이벤트 유형입니다.                                        |
| `status`           | string  | 전송 상태입니다. `success`, `failed`, `pending` 중 하나입니다. |
| `response_code`    | integer | HTTP 응답 코드입니다.                                    |
| `response_time_ms` | integer | 응답 시간(밀리초)입니다.                                    |
| `error_message`    | string  | 실패 시 에러 메시지입니다.                                   |
| `attempted_at`     | string  | 전송 시도 시간입니다.                                      |

***

## 자동 비활성화

웹훅이 연속 5회 이상 실패하면 자동으로 비활성화됩니다. 비활성화된 웹훅은 다음과 같이 표시됩니다.

```json theme={null}
{
  "id": "whk_abc123def456",
  "active": false,
  "failure_count": 5,
  "disabled_reason": "consecutive_failures",
  "disabled_at": "2025-01-16T10:00:00Z"
}
```

웹훅을 다시 활성화하려면 [웹훅 테스트](/api-reference/webhooks/test) API를 사용하세요.