Webhook 集成 - HTTP 触发器完整指南
学习如何将 Echobell webhook 集成到您的应用程序和服务中。包含 HTTP 方法、变量、模板、请求头和实际 webhook 集成示例的完整指南,实现即时通知。
Webhook 是触发 Echobell 通知最通用的方式。本综合指南涵盖了将基于 webhook 的告警集成到系统中所需了解的一切,从基本概念到高级使用模式。
用过 Direct 密钥? Direct 密钥现在已经并入频道。您的每个密钥都已自动转换为同名频道,原来的
https://hook.echobell.one/d/… URL 仍然照常可用,脚本无需任何修改。新的集成可以使用 App
中频道的 /t/ Webhook URL,它接受相同的字段。在 /t/ URL 上,notificationType
只能在您订阅时选择的级别基础上调低(见通知级别),所以如果脚本要求
calling,请以“来电”类型订阅该频道。
什么是 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 请求
GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed
POST 请求
发送 JSON 请求体:
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 发送的格式:
curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>
在浏览器中打开 URL
不带查询参数、也没有请求体的 GET 请求(浏览器或聊天应用的链接预览发出的就是这种请求)不会通知任何人。频道会返回一段简短的说明,列出它接受的字段:
{
"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 被拒绝,不会发送任何通知:
{
"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 中为它选择一种通知类型:普通(active)、时效性或来电。这个选择是频道能提醒他的最高级别。请求可以用 notificationType 指定更低的级别,但不会超过这里的设置。
例如,以“来电”类型订阅您的“生产环境”频道。故障告警不带 notificationType,会像电话一样响铃;部署完成这类日常事件发送 notificationType=active,以普通通知送达:
curl -d "title=Deploy finished&body=v2.1.0 is live¬ificationType=active" \
https://hook.echobell.one/t/<channel-token>
以“时效性”类型订阅同一频道的同事,会收到时效性通知形式的故障告警,永远不会收到来电。
开启了自定义模板的频道会忽略请求中的 notificationType:每位订阅者始终按自己选择的级别接收通知。
自定义模板
默认情况下,频道显示每个请求发送的 title、body 和 externalLink。如果请求来自一个您无法修改负载格式的服务(监控工具、CI 系统、商店后台等),请在频道设置的高级设置中开启自定义模板,并编写标题模板和正文模板。之后频道会用这些模板生成每条通知,请求中的每个查询参数和 JSON 字段都会成为变量。
通过查询参数传递变量:
GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95
或者放在 JSON 主体中:
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 请求中提供的值填充。完整语法见模板,用条件可以筛选哪些请求会发送通知。
特殊变量
externalLink:当在请求中包含此变量时,会在通知记录视图中创建一个可点击的链接(频道设置了自己的外部链接模板时除外)。
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. 命名空间下可用。完整列表与示例见条件。
常见用例
Webhook 特别适用于:
- 服务器监控和警报
- CI/CD 流程通知
- 物联网设备状态更新
- 应用程序错误跟踪
- 电子商务订单通知
- 自动化系统警报
最佳实践
- 错误处理: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。 - 413 Payload Too Large:请求体超过 1 MiB。
- 429 Too Many Requests:同一个 webhook URL 在一分钟内收到超过 120 个请求。响应带有
Retry-After头(单位为秒),请等待相应时间后再重试。 - 500:服务器临时问题,请使用指数退避重试。
- 200 OK:请求已处理。
- 速率限制:在 webhook 调用之间实施合理的延迟,以避免使通知系统过载。每个 webhook URL 每分钟最多接受 120 个请求,超出的请求会收到
429。 - 数据安全:仅与受信任的系统和服务共享 webhook URL
- 测试:在生产环境实施之前,先用最少的数据测试您的 webhook 集成
隐私和安全
请记住:
- Webhook URL 应被视为机密
- 在 webhook 请求中仅发送必要的数据
- 所有通知内容都存储在订阅者的设备上
- 我们的服务器仅处理 webhook 请求并路由通知
故障排除
如果您的 webhook 未按预期工作:
- 验证 webhook URL 是否正确
- 检查频道是否处于活动状态
- 确保您的 JSON 负载格式正确(对于 POST 请求)
- 确认您的模板中所需的所有变量都已提供(开启了自定义模板的频道)
- 检查频道是否有活跃的订阅者
需要帮助?访问我们的支持中心或通过 echobell@weelone.com 联系我们。