如何用Python调用钉钉自定义机器人Webhook

文章导读
钉钉自定义机器人通常用于把内部系统的事件推送到群聊,比如定时任务跑完、部署失败、监控告警。使用前需要先在群设置里添加机器人,拿到 webhook 地址。如果安全设置里选择了加签,调用时就要多处理签名。
📋 目录
  1. A 自定义机器人加签与签名计算
  2. B 发送文本消息与响应判断
  3. C 异常处理与超时
  4. D 频率限制与消息冗余控制
  5. E 容易忽略的检查点
A A

自定义机器人加签与签名计算

钉钉自定义机器人通常用于把内部系统的事件推送到群聊,比如定时任务跑完、部署失败、监控告警。使用前需要先在群设置里添加机器人,拿到 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 文件中,建议用环境变量保存。如果环境变量未设置,主动抛出异常,避免空值导致签名错误。

如何用Python调用钉钉自定义机器人Webhook

发送文本消息与响应判断

发送文本消息时,请求体需要是一个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。

如何用Python调用钉钉自定义机器人Webhook

异常处理与超时

网络请求不是一定成功的,所以需要在代码中捕获异常。至少应捕获requests.exceptions.RequestException,它包含了超时、连接失败、拒绝连接等常见问题。为了不拖慢主流程,建议设置超时参数,例如timeout=(3.05, 10),其中connect超时3.05秒,read超时10秒。同时,还要处理业务层的异常,比如响应的JSON解析失败。注意,钉钉返回的HTTP状态码通常是200,业务错误放在JSON里,所以不能只看status_code,必须解析响应体并判断errcode。

对于 JSON 解析失败,有可能响应体是空字符串或纯文本,需要单独记录原始内容。捕获异常时,不要只打印堆栈,要把 webhook 标识、时间、请求参数里的非敏感信息写入日志,secret 和 access_token 不要打印。

如何用Python调用钉钉自定义机器人Webhook

频率限制与消息冗余控制

钉钉对自定义机器人的调用频率有限制,具体阈值取决于企业配置,但一般需要控制发送节奏。如果短时间内连续发送大量消息,可能收到错误码表示限流。为了降低风险,可以在发送前检查消息长度,文本内容尽量简洁。另外,钉钉会忽略重复内容的行为,但并不是绝对,如果业务上需要多点重试,建议带上幂等标识,避免重复投递对用户造成打扰。若需要大批量通知,可以引入退避重试机制,但重试次数不宜过多,且每次重试间隔逐步增大。

碰到限流时,先停下看错误码,以 errcode 为准。比较稳妥的做法是第一次重试前等待 5 秒,第二次等待 15 秒,最多重试两次。如果依旧失败,就把消息缓存到本地或写进任务队列。

容易忽略的检查点

  • 确认 webhook 地址里的 access_token 与机器人页面上的一致,secret 不能为空字符串。
  • 检查服务器时间是否为标准时间,偏差过大时签名会失效。
  • 如果使用内网代理,需要给 requests 配 proxies,否则连接会超时。
  • 加签模式下,timestamp 和 sign 都必须放在 headers 里,不能塞进 URL 查询参数。

如果你在实际使用中遇到机器人收不到消息,先手动用 curl 或 Python 脚本发一条测试,确认返回 errcode=0。如果仍然失败,去钉钉管理后台重置机器人的 access_token,再更新环境变量。