企业微信机器人 webhook 告警接入指南

目标：实测企业微信（WeCom）群机器人 webhook 的告警接入全流程——群机器人创建、text/markdown 消息格式（含 @ 指定成员）、curl 推送实测（含官方端点契约回显与本地模拟端点复现）、响应码速查与限流说明。创建群机器人需真实企业微信群，标注 ⚠️ 前置；推送格式与端点逻辑可在本地完整复现。

一、环境信息

二、创建群机器人（⚠️ 前置：需要企业微信账号与群）

⚠️ 以下步骤需在企业微信客户端完成（本环境无企业主体账号，按官方流程给出，最终落点：Webhook 地址，形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<32位KEY>）。

1. 打开目标企业微信群 → 右上角 ... → 群机器人。
2. 点 添加机器人 → 输入机器人名称（如"告警机器人"）→ 添加。
3. 添加成功后复制 Webhook 地址，其中 key 参数即调用凭证（形如 693a91f6-7c2b-4bc5-a4f4-9d81e0f3a721，注意企微 key 是带连字符的 UUID 格式，与钉钉 32 位 hex token 不同）。
4. （可选）在机器人管理页设置自定义关键词（群机器人安全设置，消息需含关键词否则拒收）。

💡 说明：企微群机器人不支持加签/IP 白名单（与钉钉不同），Webhook 地址泄露即可任意推送，请勿将 key 提交到公开仓库；被移出群后 key 立即失效。

三、消息格式

3.1 text 文本（支持 @ 指定成员）

{
  "msgtype": "text",
  "text": {
    "content": "【告警】磁盘使用率超过 90%，请及时处理",
    "mentioned_list": ["zhangsan", "lisi"],
    "mentioned_mobile_list": ["13800000000"]
  }
}

💡 说明：mentioned_list 传成员 userid（非姓名），mentioned_mobile_list 传手机号；@all 用 "mentioned_list":["@all"]。不 @ 人时两个字段可省略。

3.2 markdown 富文本（告警推荐）

{
  "msgtype": "markdown",
  "markdown": {
    "content": "### 磁盘使用率过高\n> instance: **db-01**\n\n- 级别: **严重**\n- 当前值: **92%**\n- 时间: 2026-10-08 21:00:00"
  }
}

💡 说明：企微 markdown 只支持部分语法（标题、加粗、引用、列表、字体颜色 <font color=\"warning\"> 等），不支持图片；与钉钉不同，企微 markdown 没有独立 title 字段（会话列表直接展示正文首行）。

3.3 news 图文卡片

{
  "msgtype": "news",
  "news": {
    "articles": [
      {
        "title": "【告警】服务不可用",
        "description": "跳转 Grafana 查看告警详情",
        "url": "https://grafana.example.com/d/ab3RW21cd",
        "picurl": ""
      }
    ]
  }
}

四、curl 推送实测

4.1 官方端点契约回显（假 key）

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=FAKE-KEY-1234567890" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","text":{"content":"测试消息"}}'

实测回显：

{"errcode":93000,"errmsg":"invalid webhook url, hint: [1791494933183700307714922], from ip: 42.63.89.89, more info at https://open.work.weixin.qq.com/devtool/query?e=93000"}

💡 说明：errcode:93000 说明端点与协议正确、key 无效（假 key 被识别）。合法 key 返回 {"errcode":0,"errmsg":"ok"}。hint 串与 from ip 是官方排障线索，真实环境按 https://open.work.weixin.qq.com/devtool/query?e=<errcode> 查详情。

4.2 本地模拟端点复现完整推送体（无企业群可验证格式）

在本机起一个本地回显端点（监听脚本见本专栏《Alertmanager 对接钉钉-企微 webhook 告警指南》），原样打印收到的请求以校验推送体格式，随后推送同结构请求：

curl -s -X POST "http://127.0.0.1:19090/wecom" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"markdown","markdown":{"content":"### 磁盘使用率过高\n> instance: **db-01**\n\n- 级别: **严重**\n- 当前值: **92%**"}}'

实测回显（回显端点原样输出收到的请求）：

METHOD: POST
PATH: /wecom
BODY: {
  "msgtype": "markdown",
  "markdown": {
    "content": "### 磁盘使用率过高\n> instance: **db-01**\n\n- 级别: **严重**\n- 当前值: **92%**"
  }
}

💡 说明：真实接入时把 URL 换成官方端点并携带有效 key 即可；请求体格式与上述完全一致。

五、响应码速查

💡 说明：errcode 与钉钉体系不同（钉钉是 300005 token 不存在、130101 限流），对接多平台时注意区分；官方排障页：https://open.work.weixin.qq.com/devtool/query

六、常见问题

1. 返回 errcode 0 但群里没消息？

确认发送者是"群机器人"而非"应用消息"（端点不同，应用消息走 /cgi-bin/message/send 需 access_token）；另确认群未被全员免打扰。

2. 机器人 webhook 地址会失效吗？

会。机器人被移出群、群解散、企业删除机器人后 key 立即失效（对应 93001/93002/93003）；机器人被移除后重新添加会得到新 key，需同步更新告警端配置。

3. 告警频率过高被限流？

每个机器人 20 条/分钟，超限返回 45009。配合 Alertmanager 的 group_wait/repeat_interval 聚合（见《告警消息模板与最佳实践》），或多群多机器人分担。

4. 企微 markdown 能发图片吗？

不能。图片需用 image 消息类型（image.base64 + image.md5），告警场景建议 markdown 文本 + news 卡片跳转。

七、参考链接

• 企业微信群机器人配置说明：https://developer.work.weixin.qq.com/document/path/91770
• 企业微信错误码速查：https://open.work.weixin.qq.com/devtool/query
• Alertmanager 转发链路见《Alertmanager 对接钉钉-企微 webhook 告警指南》，消息规范见《告警消息模板与最佳实践》