1. 项目缘起为什么需要钉钉机器人如果你在一个技术团队里待过大概率经历过这样的场景服务器半夜挂了报警邮件淹没在收件箱里直到第二天早上才发现或者一个重要的代码合并请求Merge Request被提交了但相关同事没有及时看到导致流程卡住。在追求高效协同的今天这种依赖人工主动查看的“拉取”式通知显然已经跟不上节奏了。我们需要一种“推送”式的、即时触达的、并且能集中管理的通知机制。这就是钉钉自定义机器人诞生的背景。它本质上是一个Webhook允许你将外部系统的状态变化通过一个简单的HTTP POST请求推送到指定的钉钉群聊中。想象一下你的CI/CD流水线在构建成功或失败时自动在群里吼一嗓子你的监控系统在检测到异常指标时第一时间相关责任人甚至是你自己写的一个爬虫脚本抓取到了特定信息也能自动汇报。这一切都不需要你打开钉钉手动发送完全由程序自动化完成将人和信息在正确的时间连接起来。我最初接触它就是为了解决Jenkins构建通知的问题。每次构建完成后开发人员要么得去Jenkins页面查看要么等不定时的邮件反馈链路很长。接入钉钉机器人后构建状态秒级同步到群是成功还是失败谁提交的代码一目了然团队效率提升立竿见影。今天我就把这个从零到一的接入过程以及我踩过的坑、总结的经验毫无保留地分享出来。2. 核心概念扫盲Webhook、加签与消息类型在动手之前我们得先搞清楚几个关键概念这能帮你更好地理解后续的配置和代码而不是机械地复制粘贴。2.1 Webhook机器人的“电话号码”你可以把钉钉群自定义机器人理解为一个在群里的“虚拟成员”。而这个虚拟成员有一个专属的、保密的“电话号码”就是Webhook地址。当外部系统比如你的服务器、你的脚本需要给这个群发消息时就向这个“电话号码”Webhook URL拨打一个电话发送一个HTTP POST请求。钉钉服务器接到这个“电话”验明正身后就会把消息内容“转述”给这个群。所以整个流程的核心就是这个Webhook URL。保护好它就像保护好你的账号密码一样重要因为任何人拿到这个URL都可以冒充你的机器人向群里发消息。2.2 安全加固为什么要“加签”早期的钉钉机器人只靠Webhook URL中的access_token参数来验证身份。这存在一定的风险如果URL意外泄露比如误提交到Git仓库后果不堪设想。因此钉钉引入了“加签”Sign机制来增强安全性。加签的过程可以类比为“对暗号”。除了知道“电话号码”Webhook URL你还必须知道一个只有你和钉钉服务器知道的“暗号”签名密钥。每次“打电话”时你需要根据当前时间戳和这个密钥算出一个特殊的“签名”Sign并随请求一起发送。钉钉服务器会用同样的算法验证这个签名。只有“电话号码”和“暗号”都对得上消息才会被接收。加签的计算过程这是理解的关键你有一个secret签名密钥比如SEC123456。获取当前时间戳毫秒级比如1629781234567。把时间戳和secret用换行符\n拼接起来1629781234567\nSEC123456。对这个字符串进行HmacSHA256加密得到一个二进制结果。把这个二进制结果进行Base64编码再进行URL编码因为要放在URL里最终得到的就是签名sign。最终你的请求URL会变成原Webhook URLtimestamp1629781234567sign计算出的签名。启用加签后即使你的Webhook URL泄露攻击者不知道secret和精确的时间戳也无法伪造有效的请求安全性大大提升。所以在生产环境中强烈建议启用加签。2.3 消息类型不只是发文本钉钉机器人支持多种消息类型以适应不同场景。最常用的有text文本最基础的消息可以特定人或所有人。markdown支持Markdown语法可以发送格式更丰富的消息比如带标题、列表、链接、甚至表格的通知非常适合发送带有步骤说明或数据简报的通知。link发送一个图文链接卡片有标题、图片、摘要和跳转链接常用于发送文章、报告链接。ActionCard整体跳转/独立跳转功能更强的交互卡片可以包含多个按钮每个按钮可以跳转到不同链接。适合做简单的操作入口比如“查看详情”、“一键部署”、“确认处理”。FeedCard可以发送多个链接卡片以信息流的形式展示。选择哪种类型取决于你的通知想要达到的效果。对于简单的报警text或markdown就够了对于需要引导用户下一步操作的ActionCard是更好的选择。3. 实战第一步在钉钉群创建与配置机器人理论说再多不如动手做一遍。我们从头开始创建一个机器人。3.1 创建钉钉群并添加机器人首先你当然需要一个钉钉群。如果还没有在钉钉里随便拉几个同事或者你的小号建一个测试群。在群聊界面点击右上角的...更多-群设置-智能群助手。在这里你会看到添加机器人的选项。点击后在机器人列表里找到自定义机器人通常它会在“机器人”Tab页里图标是一个齿轮。点击添加你会进入配置页面。这里需要你给机器人起个名字比如“CI/CD通知官”、“服务器哨兵”起个一目了然的名字。选择要发送消息的群就是刚才那个测试群。设置安全设置最关键的一步自定义关键词消息内容中必须包含你设定的关键词机器人才会发送。比如你设了“报警”那么你的消息体里必须有“报警”这个词。这是一种轻量级的安全过滤但容易被绕过不建议作为主要安全手段。加签就是我们上面讲的“对暗号”。勾选“加签”后钉钉会生成一个secret签名密钥给你。务必立刻复制保存好这个secret因为它只显示一次丢失后只能重新创建机器人。IP地址段你可以设定一个或多个白名单IP只有来自这些IP的请求才会被处理。这是最推荐的安全方式尤其对于服务器IP固定的场景。将你的应用服务器或Jenkins服务器的公网IP填进去即可。注意安全设置至少选择一种。对于生产环境我的建议是“加签” “IP白名单” 双保险。关键词限制太弱一般不单独使用。配置完成后点击“完成”。钉钉会弹出一个最重要的信息窗口里面包含了你的Webhook地址。这个地址长这样https://oapi.dingtalk.com/robot/send?access_tokenxxxxxx同样请立即复制并妥善保存这个URL。关闭窗口后就再也看不到了只能重置重置会生成新的access_token和secret。3.2 一个最简单的测试用cURL发消息拿到Webhook后别急着写代码先用最原始的工具cURL测试一下通道是否畅通。打开你的终端Linux/Mac或PowerShell/CMDWindows。假设我们发送一个最简单的文本消息并且不启用加签如果你的机器人没设置加签或关键词的话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}表示成功。如果机器人设置了“自定义关键词”比如“测试”那么你的content里必须包含这个词否则会返回错误“keyword not in content”。如果启用了“加签”那么上面的命令会失败因为缺少timestamp和sign参数。我们需要构造完整的URL。4. 核心实现如何构造带签名的请求这是整个接入过程中最核心、也最容易出错的技术环节。我们以Python为例展示如何正确计算签名并发送请求。其他语言逻辑完全一致。4.1 Python实现示例与逐行解析首先安装必要的库如果需要pip install requestsimport time import hmac import hashlib import base64 import urllib.parse import requests import json def send_dingtalk_message(webhook, secret, message): 发送钉钉机器人消息 :param webhook: 完整的webhook地址不含签名参数 :param secret: 加签密钥 :param message: 要发送的消息字典符合钉钉消息格式 # 1. 生成时间戳和签名 timestamp str(round(time.time() * 1000)) 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 urllib.parse.quote_plus(base64.b64encode(hmac_code)) # 2. 构造最终的请求URL url f{webhook}timestamp{timestamp}sign{sign} # 3. 设置请求头 headers {Content-Type: application/json; charsetutf-8} # 4. 发送POST请求 try: response requests.post(url, datajson.dumps(message), headersheaders, timeout5) result response.json() if result.get(errcode) 0: print(消息发送成功) else: print(f消息发送失败: {result}) except requests.exceptions.RequestException as e: print(f网络请求异常: {e}) except json.JSONDecodeError as e: print(f响应解析异常: {e}) # 你的机器人信息 WEBHOOK https://oapi.dingtalk.com/robot/send?access_token你的token SECRET 你的加签secret # 构造一个Markdown消息 markdown_message { msgtype: markdown, markdown: { title: 服务器监控报警, text: ### **⚠️ 服务器CPU使用率过高**\n\n**告警主机**: prod-web-01\n\n**当前值**: 95%\n\n**阈值**: 80%\n\n**时间**: 2023-10-27 14:30:00\n\n[点击查看监控详情](http://your-monitor-system.com) }, at: { atMobiles: [138xxxx0000], # 要的手机号可选 isAtAll: False # 是否所有人慎用 } } # 发送消息 send_dingtalk_message(WEBHOOK, SECRET, markdown_message)关键点解析与避坑指南时间戳单位钉钉要求的时间戳是毫秒milliseconds。time.time()返回的是秒所以必须乘以1000。这是第一个常见错误点。签名字符串格式必须是{timestamp}\n{secret}中间是换行符\n不是其他符号。这是官方严格规定的格式。HMAC算法使用SHA256不是MD5或SHA1。编码顺序先进行Base64编码再进行URL编码urllib.parse.quote_plus。直接对二进制结果进行URL编码会出错。URL拼接最终的URL是webhooktimestampxxxsignxxx。注意如果你的webhook本身已经带了其他参数可能性很小这里要用?还是需要根据情况判断通常直接拼接即可。请求头Content-Type必须设置为application/json; charsetutf-8。消息体必须是合法的JSON字符串。使用json.dumps()确保中文字符等被正确编码。错误处理务必添加网络超时和JSON解析异常的处理。在生产环境中可能还需要加入重试机制例如对网络错误重试2次。4.2 其他语言的关键代码片段Shell/Bash (使用cURL):在Shell脚本中计算签名稍微麻烦一些但完全可以实现。#!/bin/bash WEBHOOKhttps://oapi.dingtalk.com/robot/send?access_tokenxxx SECRETSECxxx # 生成时间戳毫秒 timestamp$(date %s%3N) # 构造签名字符串 string_to_sign${timestamp}\n${SECRET} # 计算签名 (需要 openssl) sign$(echo -n $string_to_sign | openssl dgst -sha256 -hmac $SECRET -binary | base64) # URL编码签名 sign$(echo -n $sign | sed s//%2F/g | sed s//%3D/g | sed s/\//%2B/g) # 构造最终URL url${WEBHOOK}timestamp${timestamp}sign${sign} # 发送消息 curl $url \ -H Content-Type: application/json \ -d { msgtype: text, text: {content: Shell脚本测试报警}, at: {isAtAll: false} }注意openssl的hmac参数在较新版本中可能是-mac HMAC -macopt key:xxx需要根据系统环境调整。sed那行是为了处理URL编码/这三个字符在Base64中常见需要转换。Java (使用 Hutool 工具库极简):如果你用Java强烈推荐使用Hutool工具包它封装了钉钉机器人的方法。import cn.hutool.http.HttpUtil; import cn.hutool.json.JSONUtil; import java.util.HashMap; import java.util.Map; public class DingTalkSender { public static void main(String[] args) { String webhook https://oapi.dingtalk.com/robot/send?access_tokenxxx; String secret SECxxx; // Hutool 的 DingTalkRobotSender 类可以自动处理签名 // 这里演示手动构造理解原理 long timestamp System.currentTimeMillis(); String stringToSign timestamp \n secret; String sign cn.hutool.crypto.SecureUtil.hmacSha256(secret).digestBase64(stringToSign, true); // URL编码 sign java.net.URLEncoder.encode(sign, UTF-8); String url webhook timestamp timestamp sign sign; MapString, Object textContent new HashMap(); textContent.put(content, Java程序测试消息); MapString, Object at new HashMap(); at.put(isAtAll, false); MapString, Object message new HashMap(); message.put(msgtype, text); message.put(text, textContent); message.put(at, at); String result HttpUtil.post(url, JSONUtil.toJsonStr(message)); System.out.println(result); } }5. 高级应用与集成场景掌握了基础发送能力后我们可以把它融入到各种实际场景中。5.1 场景一Jenkins构建通知这是最经典的应用。在Jenkins任务配置的“构建后操作”中选择“钉钉通知器”。你需要安装DingTalk Plugin插件。配置要点机器人信息填入你的Webhook和Secret插件通常会自动处理签名。通知时机选择何时触发如“构建开始”、“构建成功”、“构建失败”、“构建恢复成功”等。自定义消息内容插件支持变量替换比如${PROJECT_NAME}、${BUILD_STATUS}、${BUILD_URL}。你可以构造出非常详细的Markdown消息包含提交者、分支、变更记录等。一个更灵活的做法使用Jenkins的Generic Webhook Trigger插件或直接在Pipeline脚本中使用sh步骤调用上面写的Python/Shell脚本。这样可以获得更高的自定义自由度比如根据不同的构建阶段发送不同格式的消息。5.2 场景二服务器监控报警Zabbix/Prometheus监控系统是机器人的另一个主战场。Zabbix在“报警媒介类型”中创建新的媒介类型选择“脚本”。脚本内容就是调用你的发送脚本Python/Shell并将Zabbix传递的告警参数如{ALERT.SUBJECT},{ALERT.MESSAGE}拼接到消息体中。Prometheus AlertmanagerAlertmanager本身就支持Webhook。在alertmanager.yml配置文件中添加一个webhook_configs指向一个自建的中转服务。这个中转服务接收Alertmanager的告警JSON然后将其格式化为钉钉机器人支持的Markdown或ActionCard消息再调用机器人接口发送。这样可以实现非常精美的告警卡片包含图表链接、沉默按钮等。5.3 场景三自定义脚本/应用内告警你写的任何脚本或应用程序都可以在关键节点加入通知。数据爬虫抓取到目标信息或遇到异常时发送通知。定时任务Cron Job任务执行完成或失败后发送报告。后端服务在用户注册、支付成功等业务事件发生时向内部运营群发送通知。数据库备份脚本备份成功或失败后通知DBA。这里分享一个我的实践心得对于重要的、需要及时响应的告警如线上故障使用text类型并相关人员的手机号。对于日常通知、报告如每日数据报表使用markdown或link类型让信息更结构化且不打扰个人。6. 避坑大全那些我踩过的“坑”接入过程看似简单但细节决定成败。下面是我在实践中遇到的一些典型问题。6.1 签名无效时间同步与编码之殇问题描述最常见的错误就是“sign not match”签名不匹配。排查思路检查时间戳首先确认你的服务器时间是否与网络时间同步。如果服务器时间偏差超过1小时钉钉服务器会直接拒绝。使用ntpdate或chronyd同步时间。这是最容易被忽略的一点尤其是虚拟机或容器其时钟可能漂移。检查签名字符串格式确认拼接格式是timestamp “\n” secret。在Python中使用f-string或号拼接时换行符\n必须正确。可以在计算签名前将string_to_sign打印出来肉眼检查是否真的是两行。检查编码和URL编码Base64编码确保是对HMAC-SHA256生成的**二进制数据bytes**进行Base64编码而不是对十六进制字符串编码。URL编码Base64编码后的字符串可能包含、/、。这些字符在URL中有特殊含义必须进行百分比编码Percent-Encoding。要变成%2B/变成%2F变成%3D。Python的urllib.parse.quote_plus已经正确处理了这些。但如果你自己写编码逻辑或者用其他语言很容易漏掉这一步。Secret是否正确确认复制的secret没有多余的空格或换行。最好在代码里打印一下secret的长度和内容。6.2 消息发送成功但群内不显示问题描述代码返回成功errcode:0但群里就是没消息。可能原因机器人被禁言或移除去群设置里检查一下机器人是否还在是否有发送权限。安全设置过滤关键词不匹配如果你设置了“自定义关键词”而消息内容里没有这个词消息会被静默丢弃返回成功但不发送。仔细检查消息体content或text字段里是否包含关键词。IP白名单不符你的服务器IP不在白名单里。消息同样会被静默丢弃。去机器人配置页面核对IP地址。消息格式错误虽然JSON语法正确但字段名或结构不符合钉钉要求。例如markdown消息里text字段的内容必须包含标题。可以用钉钉官方提供的消息调试工具在机器人配置页面有入口来验证你的消息体。6.3 频率限制与消息限流钉钉机器人有发送频率限制每个机器人每分钟最多发送20条消息。如果超过限制会收到“errcoce: 130101”的错误提示频率超限。应对策略合并发送对于高频但非紧急的日志或状态更新可以在本地缓存每分钟聚合一次再发送。重要性分级只将关键错误或警告通过机器人发送普通信息走日志系统。错误重试与退避在代码中捕获频率超限错误并实现指数退避重试。例如第一次重试等待2秒第二次等待4秒以此类推。6.4 功能失效问题描述消息中设置了at字段但用户没有收到提醒。原因与解决手机号对应关系atMobiles数组里填写的手机号必须是该用户绑定钉钉的手机号且该成员在群内。很多公司的员工钉钉绑定的是工作手机号而非个人手机号这里容易搞错。isAtAll权限只有群主和管理员创建的机器人并且群聊开启了“所有人”权限时isAtAll: true才会生效。否则这个设置会被忽略。文本内容中需包含对于text类型消息除了在at字段指定还需要在content文本中手动写上手机号如138xxxx0000用户才会在手机上收到强提醒Notification。markdown类型消息则不需要在文本中重复写。7. 超越基础打造更智能的机器人当你熟练使用基础功能后可以尝试一些进阶玩法让机器人变得更“聪明”。7.1 使用官方SDK简化开发钉钉为多种语言提供了官方SDK封装了签名、请求等底层细节。例如Python的dingtalk-sdk虽然官方维护可能不活跃或者社区维护的dingtalk-robot-sender。使用SDK可以让你更关注业务逻辑。# 示例使用 dingtalk-robot-sender (需 pip install dingtalk-robot-sender) from dingtalk_robot_sender import DingtalkRobot robot DingtalkRobot( webhook你的webhook, secret你的secret ) # 发送文本 robot.send_text(Hello, 钉钉机器人, is_at_allFalse) # 发送Markdown robot.send_markdown( title监控告警, text### 服务异常\n- **服务**: API Gateway\n- **状态**: Down\n- **时间**: Now, at_mobiles[138xxxx0000] )使用SDK的好处是代码更简洁但你需要了解其依赖和更新情况。7.2 构造富交互消息ActionCard的妙用ActionCard动作卡片能让你的消息从“通知”变成“操作入口”。场景当监控系统发现某台服务器磁盘空间不足时除了发送告警还可以提供一个“一键清理日志”的按钮当然这个按钮点击后是跳转到你的运维平台执行某个预定义的任务。{ msgtype: actionCard, actionCard: { title: 服务器磁盘告警, text: 服务器 **prod-db-01** 的 /var 分区使用率已超过 90%请及时处理。, singleTitle: 查看详情并处理, singleURL: https://your-ops-portal.com/server/prod-db-01?actionclean_log } }对于更复杂的场景可以使用btns字段提供多个按钮独立跳转ActionCard每个按钮可以指向不同的处理页面。7.3 消息链路追踪与回调企业高级功能对于更严格的企业应用你可能需要知道消息是否被阅读、谁点击了卡片上的按钮。这就需要用到钉钉机器人的“回调”功能。消息已读回调当消息被设置为“工作通知”模式需申请相关权限并发送给个人时可以配置回调地址钉钉会将消息的已读状态回传给你。卡片按钮回调在ActionCard的按钮中可以配置一个回调URL。当用户点击按钮时钉钉会向这个URL发送一个POST请求携带用户的身份信息和按钮信息。你可以据此在后台执行相应的业务逻辑。注意回调功能涉及更复杂的配置包括在钉钉开放平台创建应用、配置加密密钥、处理钉钉的异步事件等属于企业级集成范畴初期可以不必深究。从在群里添加一个小机器人到理解Webhook和加签的安全逻辑再到用几行代码发送第一条消息最后将其无缝集成到CI/CD、监控、业务系统中这个过程本身就是一次典型的DevOps实践。它模糊了开发、运维、测试之间的信息墙让状态自动同步让团队聚焦于处理问题本身而非寻找问题。我最深的体会是技术工具的价值不在于它本身有多复杂而在于它能否以极低的成本解决一个高频的痛点。钉钉自定义机器人正是这样一个工具。开始可能只是为了收个构建结果用着用着你就会发现无数个可以用它来“喊一嗓子”的场景。