钉钉机器人 webhook 告警接入指南

目标：实测钉钉自定义机器人 webhook 的告警接入全流程——机器人创建与安全设置（关键词/加签/IP 白名单）、text/markdown 消息格式、curl 推送实测（含官方端点契约回显与本地模拟端点复现）、加签签名计算与错误码排查。创建机器人需真实钉钉群，标注 ⚠️ 前置；推送格式与端点逻辑可在本地完整复现。

一、环境信息

二、创建机器人（⚠️ 前置：需要真实钉钉群）

⚠️ 以下步骤需在钉钉客户端完成（本环境无真实企业账号，按官方流程给出，最终落点：webhook 地址 + access_token，可选 secret）。

1. 打开目标钉钉群 → 右上角 群设置 → 智能群助手。
2. 点 添加机器人 → 选择 自定义（通过 Webhook 接入）。
3. 填写机器人名称（如"告警机器人"），选择安全设置（三选一，官方建议 加签）：
   • 自定义关键词：消息必须包含指定关键词（如"告警"），否则拒收；
   • 加签：生成 secret，请求需带签名（见 §五）；
   • IP 地址（段）：仅允许白名单来源调用。
4. 创建完成复制 Webhook 地址：https://oapi.dingtalk.com/robot/send?access_token=<32位TOKEN>（并记录加签模式下的 secret）。

💡 说明：正文以 ${DINGTALK_TOKEN} / ${DINGTALK_SECRET} 占位演示，真实值从机器人设置页获取；密钥类值不落明文。

三、消息格式

3.1 text 文本

{
  "msgtype": "text",
  "text": {
    "content": "【告警】磁盘使用率超过 90%，请及时处理"
  },
  "at": {
    "atMobiles": ["13800000000"],
    "isAtAll": false
  }
}

3.2 markdown 富文本（告警推荐）

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

💡 说明：markdown 的 title 是会话列表展示标题（纯文本），text 为正文（支持标题/引用/列表/加粗等）。告警接入推荐 markdown 类型（模板见《告警消息模板与最佳实践》）。

3.3 link 跳转卡片

{
  "msgtype": "link",
  "link": {
    "text": "跳转 Grafana 查看告警详情",
    "title": "【告警】服务不可用",
    "picUrl": "",
    "messageUrl": "https://grafana.example.com/d/ab3RW21cd"
  }
}

四、curl 推送实测

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

curl -s -X POST "https://oapi.dingtalk.com/robot/send?access_token=INVALID_TOKEN_123" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","text":{"content":"测试消息"}}'

实测回显：

{"errcode":300005,"errmsg":"token is not exist"}

💡 说明：errcode:300005 说明端点与协议正确、token 无效。合法 token 返回 {"errcode":0,"errmsg":"ok"}。注意：关键词模式下正文必须含关键词，否则返回 310000（keywords not in content）。

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

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

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

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

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

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

五、加签模式签名计算

开启"加签"安全设置后，必须携带签名参数 timestamp 与 sign：

1. timestamp = 当前毫秒时间戳
2. 拼接字符串 timestamp + "\n" + secret
3. 用 HmacSHA256 加密后 Base64 编码
4. URL 编码后作为 sign 参数

💡 机器人 token 与加签 secret 属于系统级密钥，不落明文；先从钉钉机器人管理页复制 access_token（Webhook 地址中 access_token= 后的 32 位串）与加签 secret，注入到环境变量：

export DINGTALK_TOKEN='<钉钉机器人 Webhook 地址中的 access_token 32 位串>'
export DINGTALK_SECRET='<机器人安全设置-加签页显示的 secret>'

之后在脚本/命令行中通过 ${DINGTALK_TOKEN} / ${DINGTALK_SECRET} 引用即可，签名计算与推送示例如下：

secret="${DINGTALK_SECRET}"
timestamp=$(date +%s%3N)
sign=$(printf '%s\n%s' "$timestamp" "$secret" | openssl dgst -sha256 -hmac "$secret" -binary | base64 | tr '+/' '-_' | tr -d '=')
curl -s -X POST "https://oapi.dingtalk.com/robot/send?access_token=${DINGTALK_TOKEN}&timestamp=${timestamp}&sign=${sign}" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","text":{"content":"【告警】加签模式测试"}}'

💡 说明：tr '+/' '-_' 与 tr -d '=' 对 Base64 结果做 URL 安全处理；时间戳取毫秒（date +%s%3N）。加签模式下不传签名会返回 310001（sign not match）。

六、响应码速查

七、常见问题

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

确认该群未被全员免打扰屏蔽；机器人若被群主移除需重新添加。

2. markdown 里换行不生效？

钉钉 markdown 换行需 \n（JSON 字符串内转义），正文里写 \n\n 才是段落分隔。

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

单机器人 20 条/分钟（不同版本可能不同）；配合 Alertmanager 的 group_wait/repeat_interval 聚合（见《告警消息模板与最佳实践》），或改多群多机器人分担。

4. 关键词模式和加签能否同时用？

可以同时开启，消息需同时满足（含关键词 + 正确签名）。

八、参考链接

• 钉钉自定义机器人文档：https://open.dingtalk.com/document/robots/custom-robot-access
• Alertmanager 转发链路见《Alertmanager 对接钉钉-企微 webhook 告警指南》，消息规范见《告警消息模板与最佳实践》