自定义机器人加签与签名计算
钉钉自定义机器人通常用于把内部系统的事件推送到群聊,比如定时任务跑完、部署失败、监控告警。使用前需要先在群设置里添加机器人,拿到 webhook 地址。如果安全设置里选择了加签,调用时就要多处理签名。
当钉钉自定义机器人的安全设置选择了“加签”方式,发送请求时必须额外携带timestamp和sign两个请求头。timestamp是当前毫秒时间戳,sign是用密钥secret拼接时间戳后,通过HMAC-SHA256算法计算出的十六进制摘要。具体做法:先构造待签名字符串,格式为timestamp加上换行符再加上secret,然后用Python的hmac、hashlib库计算摘要,再取base64编码,最后用urlib.parse.quote做URL编码。注意,timestamp和sign都放在请求头里,而不是放在请求体中。如果缺少这两个字段,或签名值不正确,钉钉会返回错误码310000。
签名计算可以直接用标准库实现,不需要额外安装依赖。下面是一个生成 sign 的函数:
import hmac
import hashlib
import base64
import urllib.parse
import time
def make_sign(secret: str):
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'),
digestmod=hashlib.sha256
).digest()
sign = urllib.parse.quote(base64.b64encode(hmac_code))
return timestamp, sign
secret 和 webhook 地址不要直接写在 Python 文件中,建议用环境变量保存。如果环境变量未设置,主动抛出异常,避免空值导致签名错误。
发送文本消息与响应判断
发送文本消息时,请求体需要是一个JSON对象,例如{'msgtype': 'text', 'text': {'content': '消息内容'}}。使用requests库的post方法,将URL和json参数传入即可,requests会自行处理Content-Type为application/json。收到响应后,先检查HTTP状态码是否为200,再解析返回的数据。若返回体中的errcode字段为0,说明投递成功;若为非0,则根据errmsg字段查看具体原因,比如无效的webhook地址、消息长度超限、触发频率限制等。另外,如果响应中出现errcode为310000且带有签名相关提示,需要重点检查签名计算过程。
实际发送时,要同时设置请求头和超时。下面是一个 send_text 函数:
import requests
def send_text(webhook: str, secret: str, content: str) -> dict:
timestamp, sign = make_sign(secret)
headers = {
'timestamp': timestamp,
'sign': sign
}
payload = {
'msgtype': 'text',
'text': {
'content': content
}
}
resp = requests.post(
webhook,
json=payload,
headers=headers,
timeout=(3.05, 10)
)
return resp.json()
上面这个函数返回钉响应的 JSON,调用方需要自己判断 errcode。注意 requests 不会因为 HTTP 200 就保证投递成功,必须解析 JSON。
异常处理与超时
网络请求不是一定成功的,所以需要在代码中捕获异常。至少应捕获requests.exceptions.RequestException,它包含了超时、连接失败、拒绝连接等常见问题。为了不拖慢主流程,建议设置超时参数,例如timeout=(3.05, 10),其中connect超时3.05秒,read超时10秒。同时,还要处理业务层的异常,比如响应的JSON解析失败。注意,钉钉返回的HTTP状态码通常是200,业务错误放在JSON里,所以不能只看status_code,必须解析响应体并判断errcode。
对于 JSON 解析失败,有可能响应体是空字符串或纯文本,需要单独记录原始内容。捕获异常时,不要只打印堆栈,要把 webhook 标识、时间、请求参数里的非敏感信息写入日志,secret 和 access_token 不要打印。
频率限制与消息冗余控制
钉钉对自定义机器人的调用频率有限制,具体阈值取决于企业配置,但一般需要控制发送节奏。如果短时间内连续发送大量消息,可能收到错误码表示限流。为了降低风险,可以在发送前检查消息长度,文本内容尽量简洁。另外,钉钉会忽略重复内容的行为,但并不是绝对,如果业务上需要多点重试,建议带上幂等标识,避免重复投递对用户造成打扰。若需要大批量通知,可以引入退避重试机制,但重试次数不宜过多,且每次重试间隔逐步增大。
碰到限流时,先停下看错误码,以 errcode 为准。比较稳妥的做法是第一次重试前等待 5 秒,第二次等待 15 秒,最多重试两次。如果依旧失败,就把消息缓存到本地或写进任务队列。
容易忽略的检查点
- 确认 webhook 地址里的 access_token 与机器人页面上的一致,secret 不能为空字符串。
- 检查服务器时间是否为标准时间,偏差过大时签名会失效。
- 如果使用内网代理,需要给 requests 配 proxies,否则连接会超时。
- 加签模式下,timestamp 和 sign 都必须放在 headers 里,不能塞进 URL 查询参数。
如果你在实际使用中遇到机器人收不到消息,先手动用 curl 或 Python 脚本发一条测试,确认返回 errcode=0。如果仍然失败,去钉钉管理后台重置机器人的 access_token,再更新环境变量。