# 创建 Webhook (POST)

创建一个新的 Webhook，用于接收外部服务发来的通知。

## 端点

```
POST https://api.pocketalert.app/v1/webhooks
```

## 身份验证

> **Info: 必填**
>
> 在请求中包含以下请求头之一：
> - `Token: <your-api-key>` — 从 [API 密钥](https://pocketalert.app/account/apikeys) 页面获取
> - `Authorization: Bearer <jwt-token>` — 通过 [登录](https://info.pocketalert.app/api/user/login.md) 获取

## 请求

### 请求头

| 请求头 | 必填 | 说明 |
|--------|:--------:|-------------|
| `Token` | ✅ | 你的 API 密钥 |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

### 请求体参数

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|:--------:|-------------|
| `name` | string | ✅ | Webhook 名称（例如 "Sentry"、"GitHub"） |
| `url` | string | ❌ | 接收地址 `https://p4a.me/wh/{url}` 的 slug。省略时会自动生成一个 20 位的随机 slug。必须唯一：如果 slug 已被占用，将返回 `409` |
| `message` | string | ✅ | 消息模板（使用 `*` 输出原始 JSON） |
| `application_id` | string | ❌ | 应用的 TID，用于对消息进行分类 |
| `device_id` | string | ❌ | 目标设备的 TID（省略则发送到所有设备） |
| `default_level` | string \| int | ❌ | 当负载中未指定优先级时，应用于此 Webhook 消息的默认优先级：名称（`silent`、`low`、`default`、`high`、`critical`）或整数（`-2`..`2`）。参见[消息优先级](https://info.pocketalert.app/api/messages/create.md#priority-levels)。 |
| `actions` | string | ❌ | JSON 格式的操作按钮模板。结构与[消息操作](https://info.pocketalert.app/api/messages/create.md#action-buttons)相同，但 `label`/`value` 可以包含 `%field.path%` 占位符，并根据传入的负载进行替换。以 JSON 字符串形式存储。付费功能：免费套餐会被服务端自动移除。 |

### 操作按钮模板

`actions` 允许 Webhook 生成的通知最多携带 3 个按钮，其中的 `%field.path%` 占位符会从传入的负载中替换（语法与消息模板相同）：

```json
[
  { "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
  { "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]
```

保存时会检查该模板：它必须是一个 JSON 数组，最多包含 3 个按钮，每个按钮都有有效的 `type`；不含占位符的按钮必须完全有效，否则请求将返回 `400`。

替换后，每个按钮都会按照[消息操作](https://info.pocketalert.app/api/messages/create.md#action-buttons)的规则进行验证。对于某条具体负载而言无效的按钮（例如 `view` 按钮缺少 URL 字段）会被单独丢弃，其他按钮和消息仍会正常发送。

操作按钮是付费功能。在免费套餐上，它们会在服务端被移除，消息将不含按钮发送。

### 消息模板语法

使用 `%field.path%` 从传入的 JSON 中提取值：

| 模板 | 说明 |
|----------|-------------|
| `*` | 输出整个 JSON 负载 |
| `%field%` | 提取顶层字段 |
| `%object.field%` | 提取嵌套字段 |
| `%array.0.field%` | 按索引从数组中提取 |
| `%%` | 字面量 `%`。仅在其后紧跟另一个 `%` 的单词之前需要使用，例如 `%cpu%%%`；后面带空格的 `%`（如 `90% on %host%`）保持原样即可 |

详细示例参见 [Webhook 设置](https://info.pocketalert.app/api/webhooks/settings.md)。

### 请求示例

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push",
    "message": "Push to %repository.name%: %head_commit.message%",
    "application_id": "s9h1ekk5xb46jikthl"
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Push',
    message: 'Push to %repository.name%: %head_commit.message%',
    application_id: 's9h1ekk5xb46jikthl'
  })
});

const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/webhooks',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'GitHub Push',
        'message': 'Push to %repository.name%: %head_commit.message%',
        'application_id': 's9h1ekk5xb46jikthl'
    }
)

webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
    'name' => 'GitHub Push',
    'message' => 'Push to %repository.name%: %head_commit.message%',
    'application_id' => 's9h1ekk5xb46jikthl',
]);

$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];
```

## 响应

### 成功响应

> **Tip: 201 Created**
>
> Webhook 创建成功

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `tid` | string | Webhook 的唯一标识符 |
| `name` | string | Webhook 名称 |
| `url` | string | Webhook 的 URL slug，在外部服务中使用此值 |
| `message` | string | 消息模板 |
| `actions` | string | 操作按钮的 JSON 模板（未设置时为空） |
| `is_active` | boolean | Webhook 是否处于启用状态 |

```json
{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "actions": "",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}
```

> **Tip: 使用你的 Webhook**
>
> 将外部服务配置为向以下地址发送 POST 请求：
> ```
> https://p4a.me/wh/{url}
> ```

### 错误响应

| 状态码 | 说明 |
|:------:|-------------|
| `400` | 请求错误：缺少 `name` 或 `message`，`default_level` 无效，或 `actions` 模板无效 |
| `401` | 未授权：令牌无效或缺失 |
| `403` | 禁止访问：已达到你套餐的 Webhook 数量上限 |
| `404` | 未找到：`application_id` 或 `device_id` 不存在 |
| `409` | 冲突：`url` slug 已被占用 |
