> ## 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>

등록된 웹훅 목록을 조회합니다.

***

## Query 파라미터

<ParamField query="active" type="boolean">
  활성화 상태로 필터링합니다. `true`면 활성 웹훅만, `false`면 비활성 웹훅만 반환합니다.
</ParamField>

<ParamField query="event" type="string">
  특정 이벤트를 구독하는 웹훅만 조회합니다.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  한 페이지에 반환할 웹훅 수입니다. 1에서 100 사이의 값이어야 합니다.
</ParamField>

<ParamField query="cursor" type="string">
  다음 페이지를 조회하기 위한 커서입니다.
</ParamField>

***

## Response

### 성공

웹훅 목록 조회에 성공하면 웹훅 배열과 페이지네이션 정보가 반환됩니다.

### 실패

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

***

## 요청 예시

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

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

  const { data, has_more } = await response.json();
  ```

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

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

  result = response.json()
  webhooks = result['data']
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "data": [
    {
      "id": "whk_abc123def456",
      "url": "https://your-server.com/webhooks/saju",
      "events": ["fortune.generated", "profile.created"],
      "description": "운세 생성 알림",
      "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"
    },
    {
      "id": "whk_def456ghi789",
      "url": "https://your-server.com/webhooks/daily",
      "events": ["daily.reset"],
      "description": "일일 리셋 알림",
      "active": true,
      "failure_count": 0,
      "last_triggered_at": "2025-01-16T00:00:00Z",
      "created_at": "2025-01-10T12:00:00Z",
      "updated_at": "2025-01-10T12:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}
```

***

## 응답 필드

| 필드            | 타입      | 설명                   |
| ------------- | ------- | -------------------- |
| `data`        | array   | Webhook 객체 배열입니다.    |
| `has_more`    | boolean | 다음 페이지가 있는지 여부입니다.   |
| `next_cursor` | string  | 다음 페이지 조회를 위한 커서입니다. |
| `total_count` | integer | 전체 웹훅 수입니다.          |

<Note>
  목록 조회 시 `secret` 필드는 반환되지 않습니다. 시크릿은 웹훅 생성 시에만 확인할 수 있습니다.
</Note>