---
title: Webhook 集成 - HTTP 触发器完整指南
sidebarTitle: Webhook
description: 学习如何将 Echobell webhook 集成到您的应用程序和服务中。包含 HTTP 方法、变量、模板、请求头和实际 webhook 集成示例的完整指南，实现即时通知。
---

# Webhook 集成

Webhook 是触发 Echobell 通知最通用的方式。本综合指南涵盖了将基于 webhook 的告警集成到系统中所需了解的一切，从基本概念到高级使用模式。

<Callout type="info">
  **用过 Direct 密钥？** Direct 密钥现在已经并入频道。您的每个密钥都已自动转换为同名频道，原来的
  `https://hook.echobell.one/d/…` URL 仍然照常可用，脚本无需任何修改。新的集成可以使用 App
  中频道的 `/t/` Webhook URL，它接受相同的字段。在 `/t/` URL 上，`notificationType`
  只能在您订阅时选择的级别基础上调低（见[通知级别](#通知级别)），所以如果脚本要求
  `calling`，请以“来电”类型订阅该频道。
</Callout>

## 什么是 Webhook

Webhook 是一种应用程序为其他应用程序提供实时信息的方式。这就像您给某人一个电话号码 - 当他们拨打该号码时，您的电话就会响起。在数字世界中，当一个系统中发生某事时，它会向您提供的 URL（webhook）发送 HTTP 请求，从而触发您系统中的操作。

例如，当服务器的 CPU 使用率过高时，您的监控系统可以调用 Echobell 的 webhook URL，然后触发通知来提醒您。这个过程是自动且实时的，无需您自己不断检查 CPU 使用率。

### 什么是 Webhook 端点？

Webhook 端点（endpoint）就是接收 Webhook 请求的 URL：您把这个地址粘贴到发送方服务中，它就知道每个事件该送到哪里。发送方会向该 URL 发起 HTTP 请求（通常是带 JSON 请求体的 POST），端点则返回 `200 OK` 之类的状态码，确认已收到事件。

在 Echobell 中，每个频道都有自己的 Webhook 端点，例如 `https://hook.echobell.one/t/<channel-token>`。把它作为 Webhook URL 粘贴到 Grafana、GitHub Actions、TradingView 或任何其他服务中，发往它的每个请求都会变成发给该频道订阅者的通知。URL 中的令牌用于识别频道，所以请像对待密码一样对待这个端点。

## 概述

频道是 Echobell 接收 Webhook 的方式。每个频道都有自己的 Webhook URL，当这个 URL 被调用时，频道会向所有订阅者发送通知。

创建频道只需要一个名称。默认情况下，频道会原样显示每个请求发送的 `title`、`body` 和 `externalLink`——非常适合您自己的脚本、定时任务和 CI 步骤。如果请求来自其他服务，您可以开启[自定义模板](#自定义模板)，改为根据请求中的数据生成通知。

## Webhook URL 格式

```
https://hook.echobell.one/t/{channel-token}
```

您可以在 Echobell 应用的频道详细信息视图中找到您的频道的 webhook URL。

## 发送 Webhook 请求

默认情况下，频道会从每个请求中读取四个字段。字段名不区分大小写（`title`、`Title` 和 `TITLE` 是同一个字段），可以放在 `GET` 请求的查询参数里，也可以放在 JSON 或表单编码（form）的 `POST` 请求体中。

| 字段 | 说明 |
|---|---|
| `title` | 通知标题。默认为频道名称。 |
| `body` | 通知正文。默认为空。 |
| `externalLink` | 显示在通知记录中的链接，适合指向仪表盘、日志或 Pull Request。 |
| `notificationType` | `active`、`time-sensitive` 或 `calling`。只能调低每位订阅者选择的级别——见[通知级别](#通知级别)。 |

### GET 请求

```http
GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed
```

### POST 请求

发送 JSON 请求体：

```http
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}
```

或者发送表单编码的请求体，也就是 `curl -d` 发送的格式：

```bash
curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>
```

### 在浏览器中打开 URL

不带查询参数、也没有请求体的 `GET` 请求（浏览器或聊天应用的链接预览发出的就是这种请求）不会通知任何人。频道会返回一段简短的说明，列出它接受的字段：

```json
{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}
```

加上 `title` 或 `body` 即可发送通知。`POST` 请求总会发送通知，即使请求体为空（此时标题就是频道名称）。

### 仅 POST 请求

每个频道在 Echobell App 的**高级设置**里都有一个**仅 POST 请求**开关，默认关闭。

开启后，只有 `POST` 能触发该频道。对 Webhook URL 的 `GET` 请求会以 `405 Method Not Allowed` 被拒绝，不会发送任何通知：

```json
{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}
```

`HEAD` 请求不受影响——无论该开关是否开启，它都返回 `200` 且从不触发通知。

如果 Webhook URL 会出现在自动抓取链接的地方（聊天消息、Wiki 页面、浏览器地址栏等），建议开启，这样预览或打开该 URL 都不会误发通知。如果你有调用方是用 `GET` 触发频道的，请保持关闭。

## 通知级别

每位订阅频道的人都会在 App 中为它选择一种[通知类型](/zh/docs/notification)：普通（`active`）、时效性或来电。这个选择是频道能提醒他的**最高**级别。请求可以用 `notificationType` 指定**更低**的级别，但不会超过这里的设置。

例如，以“来电”类型订阅您的“生产环境”频道。故障告警不带 `notificationType`，会像电话一样响铃；部署完成这类日常事件发送 `notificationType=active`，以普通通知送达：

```bash
curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>
```

以“时效性”类型订阅同一频道的同事，会收到时效性通知形式的故障告警，永远不会收到来电。

开启了**自定义模板**的频道会忽略请求中的 `notificationType`：每位订阅者始终按自己选择的级别接收通知。

## 自定义模板

默认情况下，频道显示每个请求发送的 `title`、`body` 和 `externalLink`。如果请求来自一个您无法修改负载格式的服务（监控工具、CI 系统、商店后台等），请在频道设置的**高级设置**中开启**自定义模板**，并编写标题模板和正文模板。之后频道会用这些模板生成每条通知，请求中的每个查询参数和 JSON 字段都会成为变量。

通过查询参数传递变量：

```http
GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95
```

或者放在 JSON 主体中：

```http
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}
```

### 模板变量

在通知模板中使用 `{{variableName}}` 语法引用变量：

```
标题：服务器 {{server_name}} 警报
内容：CPU 使用率已达到 {{cpu_usage}}%
```

触发时，这些模板将使用您的 webhook 请求中提供的值填充。完整语法见[模板](/zh/docs/template)，用[条件](/zh/docs/conditions)可以筛选哪些请求会发送通知。

### 特殊变量

- `externalLink`：当在请求中包含此变量时，会在通知记录视图中创建一个可点击的链接（频道设置了自己的外部链接模板时除外）。

```http
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}
```

## 系统时间变量（UTC）

除您发送的数据外，Echobell 还提供只读的系统时间变量，始终可用于模板与条件（UTC）。扁平字段包括：`date`、`time`、`year`、`month`、`dayOfWeek`、`hour`、`minute`、`second`。其他字段——如 `sys.dayOfWeekName`、`sys.epochMs`、`sys.epochSeconds`——仅在 `sys.` 命名空间下可用。完整列表与示例见[条件](/zh/docs/conditions)。

## 常见用例

Webhook 特别适用于：

- 服务器监控和警报
- CI/CD 流程通知
- 物联网设备状态更新
- 应用程序错误跟踪
- 电子商务订单通知
- 自动化系统警报

## 最佳实践

1. **错误处理**：Echobell 会用 HTTP 状态码和 JSON 正文回应每次 webhook 调用。先检查 HTTP 状态码，再看 `notificationTriggered`，以确认通知是否真的发出：
   - **200 OK**：请求已处理。`notificationTriggered: true` 表示已发送通知；`notificationTriggered: false` 表示有意未发送：频道条件不满足（`conditionsMet: false`），或不带参数的 `GET` 收到了用法说明。
   - **400 Bad Request**：URL 中的令牌长度不正确。
   - **404 Not Found**：没有频道使用此令牌（`code: "TRIGGER_TOKEN_NOT_FOUND"`；旧的 `/d/` URL 返回 `DIRECT_KEY_NOT_FOUND`），说明频道已删除或其 webhook URL 已重置。
   - **405 Method Not Allowed**：频道开启了[仅 POST 请求](#仅-post-请求)，而请求不是 `POST`。
   - **413 Payload Too Large**：请求体超过 1 MiB。
   - **429 Too Many Requests**：同一个 webhook URL 在一分钟内收到超过 120 个请求。响应带有 `Retry-After` 头（单位为秒），请等待相应时间后再重试。
   - **500**：服务器临时问题，请使用指数退避重试。
2. **速率限制**：在 webhook 调用之间实施合理的延迟，以避免使通知系统过载。每个 webhook URL 每分钟最多接受 120 个请求，超出的请求会收到 `429`。
3. **数据安全**：仅与受信任的系统和服务共享 webhook URL
4. **测试**：在生产环境实施之前，先用最少的数据测试您的 webhook 集成

## 隐私和安全

请记住：

- Webhook URL 应被视为机密
- 在 webhook 请求中仅发送必要的数据
- 所有通知内容都存储在订阅者的设备上
- 我们的服务器仅处理 webhook 请求并路由通知

## 故障排除

如果您的 webhook 未按预期工作：

1. 验证 webhook URL 是否正确
2. 检查频道是否处于活动状态
3. 确保您的 JSON 负载格式正确（对于 POST 请求）
4. 确认您的模板中所需的所有变量都已提供（开启了自定义模板的频道）
5. 检查频道是否有活跃的订阅者

需要帮助？访问我们的[支持中心](/zh/docs/support)或通过 echobell@weelone.com 联系我们。
