# 웹훅 기록 (GET)

특정 웹훅으로 들어온 요청의 기록을 조회합니다. 어떤 데이터가 전송되었는지, 메시지가 어떻게 렌더링되었는지, 알림이 전달되었는지 확인할 수 있습니다.

## 엔드포인트

```
GET https://api.pocketalert.app/v1/webhooks/{tid}/history
```

## 인증

> **Info: 필수**
>
> 요청에 다음 헤더 중 하나를 포함하세요:
> - `Token: <your-api-key>` — [API 키](https://pocketalert.app/account/apikeys)에서 발급받을 수 있습니다
> - `Authorization: Bearer <jwt-token>` — [로그인](https://info.pocketalert.app/api/user/login.md)으로 발급받은 토큰

## 요청

### 경로 매개변수

| 매개변수 | 타입 | 필수 | 설명 |
|-----------|------|:--------:|-------------|
| `tid` | string | ✅ | 웹훅 고유 식별자 |

### 쿼리 매개변수

| 매개변수 | 타입 | 기본값 | 설명 |
|-----------|------|:-------:|-------------|
| `page` | integer | `1` | 페이지 번호 |
| `per` | integer | `50` | 페이지당 항목 수 (최대 `200`) |
| `status` | string | — | 결과로 필터링: `success` 또는 `error` |

### 요청 예시

**cURL**

```bash
curl -X GET "https://api.pocketalert.app/v1/webhooks/kblf7mh9j8jjyeh4fx/history?per=25&status=error" \
  -H "Token: your-api-key"
```

**JavaScript**

```javascript
const tid = 'kblf7mh9j8jjyeh4fx';
const response = await fetch(`https://api.pocketalert.app/v1/webhooks/${tid}/history?per=25`, {
  headers: { 'Token': 'your-api-key' }
});
const history = await response.json();
```

**Python**

```python
import requests

tid = 'kblf7mh9j8jjyeh4fx'
response = requests.get(
    f'https://api.pocketalert.app/v1/webhooks/{tid}/history',
    headers={'Token': 'your-api-key'},
    params={'per': 25, 'status': 'error'}
)
print(response.json())
```

## 응답

### 성공 응답

> **Tip: 200 OK**
>
> 최신순으로 정렬된 요청 목록을 페이지 단위로 반환합니다

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| `requests` | array | 기록된 요청 목록 |
| `total` | integer | 보관 기간 내 전체 요청 수 |
| `page` | integer | 현재 페이지 |
| `per` | integer | 페이지당 항목 수 |
| `retention_days` | integer | 플랜에서 기록을 보관하는 일수 (`0` = 무제한) |
| `webhook` | object | `tid`, `name`, `url`, `is_active` |

`requests`의 각 항목:

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| `id` | integer | 요청 식별자 |
| `method` | string | 발신자가 사용한 HTTP 메서드 |
| `source_ip` | string | 호출자 IP 주소 |
| `content_type` | string | 요청 콘텐츠 타입 |
| `query` | string | 원본 쿼리 문자열 |
| `headers` | object | 요청 헤더 (민감한 값은 가려집니다) |
| `body` | string | 요청 페이로드 |
| `size` | integer | 페이로드 크기(바이트) |
| `status` | string | `success` 또는 `error` |
| `error_code` | string | 실패 사유, 성공 시 빈 값 |
| `rendered_message` | string | 템플릿으로 생성된 메시지 |
| `message_tid` | string | 생성된 메시지의 식별자, 실패 시 빈 값 |
| `priority` | integer | 적용된 알림 수준 |
| `duration_ms` | integer | 처리 시간 |
| `created_at` | string | 요청이 도착한 시각 |

```json
{
  "requests": [
    {
      "id": 412,
      "method": "POST",
      "source_ip": "140.82.115.16",
      "content_type": "application/json",
      "query": "",
      "headers": { "User-Agent": "GitHub-Hookshot", "Authorization": "[redacted]" },
      "body": "{\"repository\":{\"name\":\"pocketalert\"}}",
      "size": 38,
      "status": "success",
      "error_code": "",
      "rendered_message": "Push to pocketalert",
      "message_tid": "yrst1db64dbbe7euurpmanhdy",
      "priority": 1,
      "duration_ms": 24,
      "created_at": "18.07.2026 16:45:06"
    }
  ],
  "total": 1,
  "page": 1,
  "per": 50,
  "retention_days": 90,
  "webhook": {
    "tid": "kblf7mh9j8jjyeh4fx",
    "name": "GitHub Push",
    "url": "cs994rqfkk8ljngt",
    "is_active": true
  }
}
```

### 에러 코드

`status`가 `error`인 경우, `error_code`에서 실패 원인을 확인할 수 있습니다:

| 코드 | 의미 |
|------|---------|
| `inactive` | 웹훅이 비활성화되어 있어 알림이 전송되지 않았습니다 |
| `invalid_json` | 페이로드를 JSON으로 파싱할 수 없습니다 |
| `empty_message` | 템플릿이 빈 문자열로 해석되었습니다. 보통 페이로드에 존재하지 않는 `%path%`가 원인입니다 |
| `encryption_failed` | 메시지를 암호화할 수 없습니다 |
| `save_failed` | 메시지를 저장할 수 없습니다 |
| `daily_limit` | 계정의 [일일 메시지 한도](https://info.pocketalert.app/features/daily-limits.md)에 도달했습니다. 호출은 `429`를 받았고 알림은 전송되지 않았습니다. 페이로드와 렌더링된 메시지는 여기에 보관됩니다 |

### 에러 응답

| 상태 코드 | 설명 |
|:------:|-------------|
| `401` | 인증 실패 — 토큰이 잘못되었거나 없습니다 |
| `404` | 찾을 수 없음 — 웹훅이 존재하지 않습니다 |

## 참고 사항

> **Warning: 보관 기간**
>
> 기록은 플랜에 따라 일정 기간 동안 보관됩니다 (`retention_days` 참고): 무료 플랜 7일, 스타터 30일, 미디엄 90일, 라지 365일입니다. 보관 기간이 지난 요청은 자동으로 삭제되며, 웹훅 하나의 기록이 1,000건을 넘으면 가장 오래된 항목부터 자동으로 삭제됩니다.

> **Info: 개인정보**
>
> 페이로드는 메시지 내용과 같은 방식으로 개인 키를 사용해 저장 시 암호화됩니다. 저장 전에 Authorization, 쿠키, API 키 헤더는 `[redacted]`로 대체됩니다.
