不写代码，把业务系统的通知接到 IM

1. webhook-server 使用指南

项目地址：https://github.com/wildfirechat/webhook-server

很多业务系统本来就有 Webhook / 回调 / 通知功能：

• 腾讯云监控可以配置“告警回调”；
• GitLab 可以配置项目 Webhook；
• Grafana 可以配置 Contact point；
• Alertmanager 可以配置 receiver；
• 自建系统大多也能在“通知设置”里填一个 HTTP 地址。

你不需要开发对接，也不需要调 SDK。只要把业务系统里现成的 Webhook 地址，填成本服务的回调地址， 消息就会按你配置的目标发送到 IM。

整个过程只有三步：

1. 在管理后台建一个 Webhook，选好“发给谁”；
2. 把生成的回调地址填到业务系统的 Webhook 配置里；
3. 触发一次，确认 IM 收到消息。

2. 开始前，先确认三件事

1. 服务已经启动：浏览器能打开管理后台，并有一个管理账号；
2. IM 能发消息：管理后台【设置】里 IM 状态为“可用”，且有一个可用的发送者账号；
3. 业务系统能访问这个地址：公网系统需要公网 HTTPS 地址；内网系统走内网地址即可。

管理后台的登录口令和回调密钥是两回事：

• 登录口令：只给你自己登录后台用；
• 回调密钥：每个 Webhook 一把，交给业务系统用，只能触发这一条配置。

3. 第一步：在后台建一个 Webhook

登录管理后台，进入【Webhook 配置】→【+ 新建 Webhook】。

3.1. 1. 填名称

例如“腾讯云告警-服务器”“GitLab 提交通知”，方便自己区分。

3.2. 2. 选发送者

发送者是消息在 IM 里显示的账号。

• 留空：使用默认发送者（im.admin-id）；
• 点【选择发送者】：弹窗里可以按账号名、昵称、用户 ID、手机号搜索。

建议用专门的机器人/业务账号，不要用某个真人的账号代发。

3.3. 3. 选目标（消息发给谁）

点【+ 添加】，选择：

• 用户（搜索选择）：按账号名 / 昵称搜索；
• 群（搜索选择）：按群名搜索；
• 用户 / 群（手动输入）：知道 ID 时直接填。

可以加多个目标，也可以用户和群混着加。保存后目标就固定了，之后每次回调都会发给这些人/群。

3.4. 4. 选内容格式

两种方式：

• 纯文本（原文直发）：业务系统发来什么 body，就原样当消息发出去；
• JS 脚本处理：用模板或几行脚本，把 JSON 变成人看得懂的文本。

如果业务系统发的是 JSON，直接“原文直发”也能收到，只是消息里会是一串 JSON。 腾讯云、Alertmanager、Grafana、GitLab 这些常见来源，可以直接在脚本框上方选内置模板：

• 腾讯云监控（指标 / 事件告警）
• Alertmanager
• Grafana
• GitLab push
• 通用示例

3.5. 5. 保存，复制地址

保存后回到列表，点【复制链接】，会得到类似：

https://你的域名/webhook/6dfb3c01e197438d9d8b59619f0d18f2?secret=1f8e825f5f75d352697e393bdcc641be

这个地址就是给业务系统用的回调地址。

地址里的 secret 是这条配置的密钥，不要发到群里，也不要用管理后台的登录口令代替。

4. 第二步：填到业务系统的 Webhook 里

不同系统的入口名字不一样，但本质都是同一个东西：一个能填 URL、能选事件、能发 POST 的配置页。

通用填法：

如果系统支持自定义请求头，优先用请求头传密钥；不支持时再用 URL 里的 ?secret=。

4.1. 腾讯云监控

1. 腾讯云可观测平台 → 告警管理 → 告警配置 → 通知模板；
2. 新建通知模板，在“接口回调”里填本服务的地址；
3. 密钥可以放 URL，也可以在自定义请求头里加 X-Webhook-Secret；
4. 保存后，把通知模板绑定到告警策略；
5. 回到本服务编辑配置，文本内容选“JS 脚本处理”，插入“腾讯云监控（指标 / 事件告警）”模板；
6. 在测试面板选择“腾讯云：指标告警”或“腾讯云：事件告警（恢复）”，点运行可以先看效果。

腾讯云触发和恢复都会回调；模板会自动区分：

【告警】CPU 告警
级别：严重　类型：指标
对象：云服务器-基础监控（unInstanceId=ins-xxx）
指标/事件：基础CPU利用率（当前值 95%）
时间：2026-11-13 10:00:00
持续：300 秒

4.2. GitLab

项目 → Settings → Webhooks → Add new webhook：

• URL 填本服务地址（带 ?secret=）；
• 勾选需要的事件（Push events、Merge request events 等）；
• 保存后点 Test，选择 Push events。

然后在本服务里插入“GitLab push”文本模板即可。

GitLab 的 “Secret token” 字段发的是 X-Gitlab-Token，本服务不识别这个头； 密钥请放在 URL 的 ?secret= 里。

4.3. Grafana

Alerting → Contact points → 新建 Webhook：

• URL 填本服务地址，密钥放 URL 的 ?secret=（Grafana 的 Authorization 头不是本服务的密钥头）；
• 保存后在告警规则里绑定这个 Contact point。

文本模板选“Grafana”。

4.4. Alertmanager

在 receiver 里配置：

receivers:
  - name: webhook-server
    webhook_configs:
      - url: 'https://你的域名/webhook/配置ID?secret=密钥'

目标模板和文本模板都选 Alertmanager，receiver 字段可以直接映射成值班账号。

4.5. 自建系统 / 其他系统

找“Webhook”“回调”“通知”“HTTP 推送”这类设置，填本服务地址即可。 只要对方能发 POST、能带一个自定义请求头（或 URL 参数），就能接。

不要把本服务地址填成钉钉/企业微信/飞书机器人的地址——那些是“消息最终展示的平台”。 本服务负责把消息送到 IM；如果业务系统只会发钉钉格式，可以在本服务里选/写一个文本模板转换，不需要改业务系统代码。

5. 第三步：触发一次，验证

在业务系统里点“测试”，或者实际触发一次告警。

然后：

1. 看 IM 是否收到消息；
2. 回到本服务【调用记录】，看这一条记录：
   • 发给了哪些用户/群；
   • 成功几个、失败几个；
   • 失败原因；
   • 来源 IP、时间、耗时。

如果没收到，先看调用记录里有没有这次请求：

• 没有记录：业务系统根本没发出来，或地址填错、网络不通；
• 有记录但失败：看失败原因，常见的是密钥不对、配置停用、目标用户不存在、IM 不可用。

6. 消息内容怎么变好看（仍然不用开发）

大多数场景不需要写代码：

1. 先选一个接近的内置模板；
2. 在“测试”面板里选择对应的样例数据；
3. 点“运行”，看输出的文本；
4. 满意就保存。

模板覆盖了腾讯云、Alertmanager、Grafana、GitLab 和通用 JSON。 如果字段对不上，可以：

• 换一个样例/模板；
• 或者只改模板里的字段名（仍然是在页面上改，不用发版、不用重启）；
• 实在需要复杂逻辑，再用几行 JS，例如按标签映射值班人。

发送目标也一样：固定目标适合“永远发给这个群”，脚本目标适合“按告警内容找人”。

7. 常见问题

8. 上线前检查清单

• 业务系统填的是本服务的回调地址，不是 IM 地址，也不是钉钉/飞书机器人地址；
• 密钥通过请求头或 URL 正确传入，没有把管理后台口令填进去；
• 目标用户/群已经在 IM 里存在；
• 发送者是专门的机器人/业务账号；
• 管理后台只开给内网/办公网，对外回调走 HTTPS；
• 触发一次测试，调用记录里能看到成功结果。

9. 一句话总结

业务系统本来就会发 Webhook，你只需要在它里面填一个地址； 本服务负责验密钥、找对人、把 JSON 变成消息、发到 IM，并留下记录。

不用开发对接，配置完就能用。