# Webhook 历史记录 (GET)

获取某个 Webhook 的入站请求历史，包括发送了什么、渲染成了什么，以及告警是否已成功投递。

## 端点

```
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 | ✅ | Webhook 唯一标识符 |

### 查询参数

| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|:-------:|-------------|
| `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` | Webhook 已禁用，因此未发送告警 |
| `invalid_json` | 负载无法解析为 JSON |
| `empty_message` | 模板解析结果为空字符串，通常是因为负载中不存在对应的 `%path%` |
| `encryption_failed` | 消息加密失败 |
| `save_failed` | 消息存储失败 |
| `daily_limit` | 账户已达到[每日消息上限](https://info.pocketalert.app/features/daily-limits.md)。调用返回 `429`，未发送告警；此处会保留负载和渲染后的消息 |

### 错误响应

| 状态码 | 描述 |
|:------:|-------------|
| `401` | 未授权：令牌无效或缺失 |
| `404` | 未找到：Webhook 不存在 |

## 注意事项

> **Warning: 保留期**
>
> 历史记录的保留天数取决于你的套餐（见 `retention_days`）：免费套餐为 7 天，Starter 为 30 天，Medium 为 90 天，Large 为 365 天。超过保留期的请求会被自动删除；当单个 Webhook 的记录超过 1,000 条时，最早的记录也会被自动删除。

> **Info: 隐私**
>
> 负载会使用你的个人密钥加密存储，与消息内容的加密方式相同。在存储前，Authorization、Cookie 和 API 密钥相关的请求头会被替换为 `[redacted]`。
