钉钉机器人自动发送消息到群：Webhook原理与Python实现

简介一套基于Java实现的钉钉机器人自动推送源码包面向需要为团队搭建消息通知、系统报警或任务进度汇报功能的Java开发者。包内完整展示了通过Webhook接口向钉钉群发送自定义文本消息的实现流程包含群机器人创建、消息JSON构建、POST请求发送与响应状态判断等关键环节。压缩包共161个文件以Java源码、XML配置、JavaScript前端资源、JSON示例及properties配置为主整体仅382KB工程结构清晰便于直接导入IDE查看运行。已有2296人学习使用。源码中提供了AlarmService类及sendAlarmMessage方法代码简洁可读稍加改动即可接入定时任务框架适用的场景包括服务异常实时告警、批量任务完成提醒、每日工作摘要推送等适合作为企业级自动化通知模块的基础模板。1. 从群里反复轰炸的告警说起这个 rar 到底解决什么做过运维或后端开发的人大概率都经历过这种场景脚本跑挂了、磁盘快满了、每日报表出来了需要立刻通知到人。群里 人太累邮件又没人看最顺手的方式就是往钉钉群里丢一条消息。钉钉的“自定义机器人”提供的就是这个能力——不需要申请企业应用不需要审核只要在群里添加一个机器人拿到一串 Webhook 地址然后往这个地址 POST 一段 JSON消息就自动出现在群里。你手上这个“实现钉钉机器人自动发送自定义信息到钉钉群(对应源码).rar”核心就是把这件事从“手动 curl 一条”变成“程序里随时能调、内容还能动态组装”的自动化工具。适合谁适合要用脚本发告警、发报表、发 CI/CD 构建结果的开发、运维、测试同学也适合想给钉钉群加一点“自动播报”能力的业务人员。下面我按自己落地这套方案的路子从原理、代码到坑完整讲一遍。2. 钉钉自定义机器人的原理与创建步骤先拿到一个能用的 Webhook2.1 自定义机器人是什么和“企业内部应用机器人”差在哪钉钉群里能加的机器人分两类。一类是“企业内部应用机器人”需要你在钉钉开放平台创建一个应用拿到 AppKey/AppSecret走 OAuth 流程能发更复杂的消息也能读取会话、组织信息——但开发和权限申请都比较重。另一类就是“自定义机器人”它本质是一个 Webhook 地址钉钉把这个地址绑定到你所在的群。任何能访问这个地址的客户端都可以往群里推消息不需要身份认证只要拼对 JSON 格式。我们做“自动发送自定义信息”绝大多数场景用自定义机器人就够了。它支持的消息类型包括 text、markdown、link、actionCard、feedCard覆盖普通文本、富文本、图文卡片、跳转按钮这些常见需求。限制也很明显不能主动接收消息不能读取群成员列表只能“单向推送”。如果你需要双向交互那就得换企业内部应用机器人甚至要上一套服务端回调。自定义机器人的工作流程极简单你在群里添加机器人拿到一个形如https://oapi.dingtalk.com/robot/send?access_tokenxxxxxxxx的地址。你的程序往这个 URL 发起 HTTP POST 请求Content-Type 是application/jsonBody 是一个 JSON 对象其中msgtype指定消息类型后面跟具体内容。钉钉接收后解析校验合法就推送到群里。这个“校验”环节就是我们要重点关注的三个安全设置自定义关键词、加签、IP 白名单。2.2 在钉钉群里添加机器人手机端和电脑端的完整步骤添加机器人的入口在群设置里电脑端和手机端基本一致只是层级略不同。我习惯用电脑端操作看得清楚打开目标钉钉群点击右上角“群设置”图标。进入“智能群助手”或“机器人”管理页不同版本钉钉的叫法略有差异找“添加机器人”按钮。在机器人列表里选“自定义”类型点击“添加”。给机器人起个名字比如“发布告警机器人”头像可自定义。关键一步安全设置。这里有三个选项——自定义关键词、加签、IP 地址段。根据你的使用场景选一个或多个。点击“完成”钉钉会生成一个 Webhook 地址复制保存好。这里要提醒一句Webhook 地址等于群消息的“门禁钥匙”谁拿到它谁就能往群里发消息。所以安全设置必须认真对待。如果只是自己调试选“自定义关键词”设置一个不容易被别人猜到的词比如你的项目代号ZabbixAlert那么以后每条消息正文里必须包含这个词否则会被钉钉拒绝。但这个方案不够安全因为只要别人拿到 Webhook把关键词带上就能伪造。我建议生产环境用“加签”方式钉钉会要求你填一个密钥Secret发送时需要在请求头带上时间戳和用 HMAC-SHA256 算法算出的签名钉钉校验通过才接受。后面写代码时我会把签名算法一并给出。2.3 安全设置选型关键词、加签、IP 白名单怎么组合这三个设置不是三选一而是可以多选。选了多个时要求同时满足。我一般这样配个人学习/临时调试只选“自定义关键词”关键词设为测试图省事。公司内部服务选“加签”密钥模式代码里维护 Secret安全性和使用灵活性平衡最好。固定服务器发消息在加签基础上再加“IP 地址段”白名单填服务器公网出口 IP这样即使 Webhook 和 Secret 泄露攻击者从其他 IP 请求也会被拒。选“加签”后钉钉会让你复制一个 Secret通常以SEC开头。这个密钥千万别提交到 Git。我见过一个项目把SEC开头的一串明文写死在代码里结果仓库公开后被人往群里刷了一下午广告。正确做法是放到环境变量或本地配置文件中并加入.gitignore。2.4 用 curl 验证 Webhook 是否可用三条命令确认通路拿到 Webhook 后先用手工验证一下不要直接写代码。这是最快排除“地址错误、格式错误、安全设置不匹配”的路径。打开终端执行以下命令curl https://oapi.dingtalk.com/robot/send?access_token你的_token \ -H Content-Type: application/json \ -d {msgtype: text, text: {content: 测试消息关键词要带上}}如果返回 JSON 为{errcode:0,errmsg:ok}说明通路没问题群里应该已经出现“测试消息”了。如果返回errcode非 0对照下面信息310000表示 access_token 错误检查是否复制完整。310001或310002表示关键词不匹配或安全设置未通过检查消息内容是否包含你设的关键词。310003表示 IP 不在白名单内检查请求来源 IP。这一步虽然简单却能帮你把问题分割开。Webhook 能用后再交给程序后续排错就只聚焦代码本身。我自己每次新建机器人都会先跑这条 curl省掉后面无数猜疑。3. 用 Python 把“自定义信息”发进群里最小可跑通脚本3.1 源码包里的常见组成以及我为什么选择 Python你拿到的这个.rar按标题里“对应源码”四个字里面应当包含的就是发送端的实现而不是钉钉服务端代码。常见的实现语言有 Python、Java、Shell、Go。我建议用 Python原因有三一是requests库让 HTTP 调用简洁到极致二是字符串模板、JSON 序列化都是原生能力三是后续接监控数据、读文件、调 API 都很顺手。无论压缩包里是什么语言落地思路完全一致构造 JSON → 计算签名 → POST 到 Webhook。在 Open 源码之前先自己动手把发送函数写出来你才能看懂别人代码里的参数含义。下面我给出一套完整且可直接套用的 Python 实现包含“无加签”和“加签”两个版本覆盖大多数使用场景。3.2 最小发送脚本text 消息与 verify 返回没有配置“加签”时代码非常简单。新建ding_send.py内容如下import requests import json # 你的 Webhook 地址注意 access_token 那段不要外泄 WEBHOOK_URL https://oapi.dingtalk.com/robot/send?access_tokenyour_token def send_text(content): 发送纯文本消息。 content: 消息正文如果机器人设置了关键词必须包含关键词 headers {Content-Type: application/json} payload { msgtype: text, text: { content: content } } resp requests.post(WEBHOOK_URL, headersheaders, datajson.dumps(payload)) result resp.json() if result.get(errcode) ! 0: print(f发送失败: {result}) else: print(发送成功) return result if __name__ __main__: send_text(【测试】钉钉机器人自动发送这条消息来自 Python 脚本)逻辑说明requests.post的data参数接收的是字符串所以先用json.dumps(payload)序列化。headers里必须声明Content-Type为application/json因为钉钉接口只认 JSON 格式如果少了这行部分服务器会返回 415 或解析错误。resp.json()把返回的 JSON 转成字典errcode为 0 表示钉钉已接受消息。注意这里不保证消息一定显示在群里因为还存在异步推送节奏几乎不会丢但大量并发时存在频率限制后面避坑章细说。3.3 加签模式下的发送函数签名算法完整实现如果机器人选择了“加签”安全设置发送时需要在请求体中增加timestamp和sign两个字段。签名算法是把时间戳和密钥拼成字符串timestamp \n secret用 HMAC-SHA256 算法加密再对结果做 Base64 编码最后把特殊字符 URL 编码。代码实现如下import requests import json import time import hmac import hashlib import base64 from urllib.parse import quote_plus WEBHOOK_URL https://oapi.dingtalk.com/robot/send?access_tokenyour_token SECRET SEC你的密钥 # 建议从环境变量读取 def generate_sign(timestamp): 根据时间戳和密钥生成钉钉签名 string_to_sign f{timestamp}\n{SECRET} hmac_code hmac.new( SECRET.encode(utf-8), string_to_sign.encode(utf-8), digestmodhashlib.sha256 ).digest() sign quote_plus(base64.b64encode(hmac_code)) return sign def send_text_with_sign(content): timestamp round(time.time() * 1000) sign generate_sign(timestamp) # 注意签名参数需要拼在 URL 上而不是 Body 里 url f{WEBHOOK_URL}timestamp{timestamp}sign{sign} headers {Content-Type: application/json} payload { msgtype: text, text: {content: content} } resp requests.post(url, headersheaders, datajson.dumps(payload)) result resp.json() if result.get(errcode) ! 0: print(f发送失败: {result}) return result if __name__ __main__: send_text_with_sign(【加签测试】这条消息经过了 HMAC 签名)参数说明time.time()返回的是秒钉钉要求毫秒级时间戳所以乘以 1000 并取整。quote_plus对 Base64 结果中的/等字符做 URL 编码这是钉钉文档明确要求的漏掉会导致验签失败。hmac.new的三个参数中密钥和待签名串都必须编码成 bytesdigestmodhashlib.sha256是固定算法。生成签名后把它和 timestamp 拼接在 Webhook URL 后面注意要用连接因为 Webhook 地址本身已带?access_token...查询参数。加签模式强烈建议用于生产环境。虽然代码比无签模式多几行但能有效防止 Webhook 被滥用。我自己写的监控脚本全部使用加签关键词模式只用于本地玩。3.4 发送 Markdown 和 link 消息同一套框架扩展消息类型实际工作中纯文本往往不够。比如要把一行行的监控指标发到群里用 Markdown 更易读。钉钉的 Markdown 消息通过msgtype为markdown发送title是首屏标题text里支持 Markdown 语法。改造上面的函数只需换payloaddef send_markdown(title, markdown_text, is_at_allFalse): payload { msgtype: markdown, markdown: { title: title, text: markdown_text }, at: { isAtAll: is_at_all } } resp requests.post(url, headersheaders, datajson.dumps(payload)) # 后续处理和文本消息相同at字段用于 群成员isAtAll设为true会 所有人。若想 特定人可以用atMobiles传入手机号列表比如atMobiles: [138xxxx]。注意钉钉要求被 的人必须在群里且手机号是钉钉注册手机号。Markdown 文本中不要使用外链图片钉钉对图片渲染支持有限最好用的格式但图片服务器必须有公网访问能力否则群里显示空白。链路消息link适合推送一个带跳转地址的摘要。payload 结构为payload { msgtype: link, link: { title: 报表已生成, text: 点击查看昨日销售数据, picUrl: http://example.com/cover.jpg, messageUrl: http://example.com/report } }messageUrl是必填项钉钉客户端点击消息会跳转到这个地址。picUrl可选但要注意 HTTPS 证书有效否则部分客户端不展示缩略图。4. 让信息“自动”起来定时任务、动态内容与多群推送4.1 从命令行、文件、API 里读取自定义内容消息内容如果写死在脚本里那叫“手动发送”不叫“自动发送”。自动化的第一步是让消息内容能随环境变化。常见做法有三种执行一条命令把输出作为消息正文。读取本地文件比如日志、报表。调用内部 API拿到 JSON 数据拼成可读文本。下面这段代码体现了“从文件读取并发送”的模式def send_file_content(file_path, keyword【监控】): with open(file_path, r, encodingutf-8) as f: content f.read() # 如果文件过长截断前 2000 字避免超出钉钉消息长度限制 if len(content) 2000: content content[:2000] \n...内容过长已截断 send_text(keyword \n content)参数说明钉钉自定义机器人对消息正文长度有限制text 消息最大 5000 字符markdown 消息最大 20000 字符。但实际推荐控制在 2000 以内因为手机上查看太长内容体验很差且钉钉对超长消息可能出现发送失败。如果你要发送日志末尾建议只截取最后几十行content \n.join(content.splitlines()[-50:])。从 API 读取数据再发送是把运维告警做成“自动播报”的典型。我曾在机房温度监控里做过一版每五分钟读取传感器 API温度超过阈值就发送告警消息。核心代码就是把 JSON 解析后塞进模板import requests def fetch_sensor_data(): resp requests.get(http://sensor.local/api/temp, timeout5) return resp.json() def build_alert_message(data): return f【温度告警】机房当前温度 {data[temp]}℃湿度 {data[humidity]}%这种模式下发送函数不再关注数据来源只负责格式化与推送职责清晰。4.2 用 cron 和系统计划任务实现定时发送消息内容动态化之后还要解决“触发方式”。Linux 下最常用的是 cron 表。打开 crontabcrontab -e添加一行表示每天 9 点执行一次发送脚本0 9 * * * /usr/bin/python3 /opt/ding/ding_send.py /var/log/ding_send.log 21把“每天 9 点”换成“每 5 分钟”就是*/5 * * * *。cron 的语法不做展开但有几个关键细节脚本内路径要用绝对路径cron 环境变量和终端不一样相对路径容易找不到文件。脚本输出的日志要重定向到文件便于排查问题。如果脚本需要读取环境变量比如密钥cron 默认不加载/etc/profile可以用/usr/bin/env或直接在脚本里指定默认值我一般会在脚本顶部加一段从文件读取密钥的逻辑而不是依赖系统环境变量。Windows 用户可以打开“任务计划程序”创建基本任务触发器选“每天”或“重复任务”操作里填python和脚本路径。原理和 cron 完全一样只是界面操作。4.3 多群推送与配置管理Webhook 列表优雅管理如果消息要同时发到多个钉钉群比如运维群、开发群、管理层群最简单的办法是定义 Webhook 列表遍历发送WEBHOOKS { ops: https://oapi.dingtalk.com/robot/send?access_tokenops_token, dev: https://oapi.dingtalk.com/robot/send?access_tokendev_token, mgmt: https://oapi.dingtalk.com/robot/send?access_tokenmgmt_token, } def send_to_multi_groups(group_names, content): for group in group_names: url WEBHOOKS[group] # 调用前面定义的 send_text_by_url(url, content)这里注意不要在一个脚本里硬编码所有群名。更稳妥的做法是使用 YAML 或 JSON 配置文件groups: ops: webhook_url dev: webhook_url mgmt: webhook_url脚本启动时加载配置需要发哪个群就传哪个 key。这样新增群不用改代码运维同事拿到ops这个 key 就能用。多群发送时还要考虑失败隔离一个群发送失败不应影响其他群。代码中要为每个群的请求单独try/except并记录哪个群失败便于重试。5. 避坑签名、关键词、URL 编码、消息频率这些坑我全踩过5.1 加签模式签名总是验签失败现象配置好 Secret 后请求返回errcode为 310001 或 310002提示签名错误。原因最常见的有三种。一是时间戳timestamp用的是秒而不是毫秒导致签名串和钉钉验签时对不上因为钉钉要求毫秒级。二是 Base64 编码后的结果没有做 URL 编码/等字符在 URL 传参时被转义或截断。三是拼接 URL 时把timestamp和sign放到了 Body 里而正确要求放在 URL 查询参数中。解决按我上文代码timestamp round(time.time() * 1000)quote_plus(base64.b64encode(...))并且用url f{webhook}timestamp{timestamp}sign{sign}。如果还不行打印出最终请求的 URL在浏览器里去掉sign参数用在线 HMAC 工具验证算法。另外服务器时间偏差也会导致验签失败钉钉允许的时间偏差是 1 小时一般不会踩到但如果你在容器里运行注意镜像时间是否同步。5.2 明明设了关键词发送还是被拒现象消息内容里包含关键词但钉钉返回310000或其他错误或者关键词规则不生效。原因钉钉的“自定义关键词”匹配是要求消息正文中完整包含设置的词且关键词不能有空格或特殊符号。如果你设置的关键词是告警而消息正文是【告警信息】能匹配但如果消息正文是告 警中间有空格就匹配不上。还有一个隐藏坑text消息看的是text.content字段markdown消息看的是markdown.text字段而link消息看的是link.title字段。如果你发的是 link 消息关键词放在link.text里钉钉不会校验因为校验规则只针对特定字段。解决发送不同类型消息时确认关键词被放在了正确的位置。最省事的方法是关键词设为项目缩写比如DING-ALERT然后在所有消息正文开头拼上DING-ALERT不管是 text 还是 markdown 都能覆盖。5.3 发送偶发失败但手动重试又能成功现象脚本每天定时发送偶尔几天收到一次“发送失败”日志但手动跑一遍又正常。原因大概率是钉钉的限流策略。自定义机器人对单个机器人的发送频率有严格控制普通消息每个机器人每分钟最多 20 条钉钉官方建议单发间隔不小于 1 秒。如果你的脚本在同一秒内向同一个 Webhook 发送多条消息比如遍历多个群每个群各一条很容易触发限流返回errcode为 310000 或稍后出现 130101。解决在发送循环中加入time.sleep(1)并且对失败请求做指数退避重试。我见过更稳妥的方案把要发送的消息先存到一个队列里由独立线程按每秒 1 条的速度消费彻底避开限流。另外如果是企业内部的机器人钉钉还有 10 分钟 100 条的限制用多群广播时更要控制总量。5.4 Markdown 消息里的换行和左尖括号显示异常现象发送 Markdown 消息换行没生效或者 HTML 标签直接显示成纯文本。原因钉钉的 Markdown 语法不是标准 CommonMark而是裁剪过的子集。空行换行有时需要两个空格加回车或者使用br标签。font colorred这类 HTML 标签只在部分客户端中支持且不是标准渲染。我踩过最深的一个坑是在文本里用了和表示“小于/大于”结果被解析成标签后面的内容全部被吞掉。解决Markdown 文本中需要展示或时用 HTML 实体lt;和gt;代替。换行优先使用\n\n空行如果不行再试br。测试时把 Markdown 文本先粘贴到钉钉笔记里看渲染效果再回填到脚本。5.5 Webhook 地址泄露群里被刷广告现象群里突然出现大量非预期的消息内容多为广告或无关信息。原因Webhook 地址被提交到了公开仓库或者分享到群里被工具抓取。自定义机器人本身没有认证任何人拿到 URL 就能发消息除非你配置了加签或 IP 白名单。解决立即在钉钉群设置中“删除机器人”然后重新添加并生成新 Webhook。修改代码中 URL同时把 Secret 从代码里移走。如果项目代码是公开的可以写一个轻量代理服务把 Webhook 地址藏在服务端内部系统只调用代理接口。代理层可以加一层简单的令牌认证从根上防止地址泄露后被滥用。6. 收尾技巧把单调的文本消息升级成钉钉卡片消息文本消息虽然可靠但在群聊里容易被淹没尤其多条告警同时出现时根本分不清优先级。我在跑了一段时间纯文本告警后把所有关键告警切换成了actionCard消息。它自带标题、加粗文本、按钮跳转一眼就能看出“这个需要登录服务器处理”比在文字里拼!!!有效得多。卡片消息的 payload 结构如下payload { msgtype: actionCard, actionCard: { title: 【故障】Web 服务器响应超时, text: #### 详细指标\n\n- 错误率**12.5%**\n- 平均响应**2.3s**\n- 当前时间2024-01-01 12:00:00\n\n请及时处理, btnOrientation: 1, btns: [ { title: 查看监控后台, actionURL: https://monitor.example.com }, { title: 确认处理, actionURL: https://ops.example.com/handle?id123 } ] } }参数说明btnOrientation为1表示按钮垂直排列0为水平排列。actionURL在 PC 端直接跳转手机端会先提示“网页版钉钉打开”体验稍差但可以用。实际使用时actionCard的text部分同样要遵守 Markdown 子集规范换行用\n\n。我现在的习惯是普通通知用 text 消息带数据看板的用 markdown需要人处理的告警一律用 actionCard并配上“确认处理”按钮链接到工单系统。这样群里 50 条消息时大家只会盯着带按钮的卡片。关于验证我每次改完脚本不会直接部署而是先往一个专用测试群发一条带时间戳的消息import time send_text(f[自检] {time.strftime(%Y-%m-%d %H:%M:%S)} 发送链路正常)连续发几条确认errcode0且群里消息顺序正确再交给 cron 调度。这套习惯帮我避开了多次“脚本配置错了都不知道”的尴尬。希望这个方案能帮你在钉钉群里建立起靠谱的自动通知能力少熬几个处理告警的夜。本文还有配套的精品资源点击获取