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。
notificationTypeactive、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&notificationType=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 流程通知
  • 物联网设备状态更新
  • 应用程序错误跟踪
  • 电子商务订单通知
  • 自动化系统警报

最佳实践

  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。
    • 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. 检查频道是否有活跃的订阅者

需要帮助?访问我们的支持中心或通过 echobell@weelone.com 联系我们。