钉钉自定义机器人的 webhook 地址本身没有固定的有效期，但如果出现发送失败，通常是因为机器人被移除、安全设置变更或密钥轮换导致。最稳妥的处理方式是进入群设置检查机器人状态，必要时重新添加并更新代码中的地址。

命令速用版

如果你需要快速测试新地址是否可用，可以在终端执行以下 curl 命令。注意替换你的 access_token 和实际内容。

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

如果返回 errcode 为 0，说明地址有效。

为什么会这样

很多用户认为 webhook 会像密码一样定期过期，但实际上钉钉自定义机器人的 access_token 长期有效，除非发生以下情况：

• 机器人被管理员从群聊中移除
• 群聊安全设置升级，例如开启了 IP 白名单但请求 IP 不在列表内
• 加签密钥（Secret）被重置，导致旧签名失效
• 机器人被禁用或删除

因此，所谓的“失效”大多是配置不一致导致的权限拒绝。

分步处理（平滑切换）

按照以下顺序操作，可以避免盲目重建导致的通知中断。

1. 检查报错信息：查看业务日志中钉钉接口返回的 JSON。如果提示 invalid access_token，说明地址彻底不可用；如果提示 signature verification failed，说明密钥不匹配。
2. 进入群设置：在钉钉群右上角点击设置，找到“智能群助手”或“机器人”列表。
3. 先添加新机器人：不要立即移除旧机器人。点击添加“自定义”机器人，生成新的 webhook 地址和 Secret。此时群内会有两个机器人，旧业务不受影响。
4. 更新代码配置：将新地址和密钥更新到你的应用程序配置中。如果使用了 IP 白名单，务必将服务器出口 IP 加入钉钉后台设置。
5. 验证新配置：使用新配置发送测试消息，确认接收正常且日志无报错。
6. 移除旧机器人：确认新配置稳定运行后，再在群设置中移除旧的机器人，完成切换。

签名计算代码示例

如果机器人开启了“加签”安全设置，发送请求时必须携带 timestamp 和 sign 参数。以下是 Python 版本的签名生成示例：

import time
import hmac
import hashlib
import base64
import urllib.parse

def get_dingtalk_sign(secret, timestamp):
    secret_enc = secret.encode('utf-8')
    string_to_sign = '{}\n{}'.format(timestamp, secret)
    string_to_sign_enc = string_to_sign.encode('utf-8')
    hmac_code = hmac.new(secret_enc, string_to_sign_enc, digestmod=hashlib.sha256).digest()
    sign = urllib.parse.quote_plus(base64.b64encode(hmac_code))
    return sign

# 使用示例
timestamp = str(round(time.time() * 1000))
secret = 'YOUR_SECRET'
sign = get_dingtalk_sign(secret, timestamp)
webhook = 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN×tamp={}&sign={}'.format(timestamp, sign)

怎么验证是否生效

配置完成后，不要等待业务触发，主动发送一条测试消息。

• 观察钉钉群内是否收到消息。
• 检查发送端日志，确认接口返回 HTTP 200 且 errcode 为 0。
• 如果使用了加签，确保时间戳和签名计算逻辑与新 Secret 匹配。

常见坑

• IP 白名单遗漏：新机器人可能默认开启了安全设置，如果服务器 IP 变动或未配置白名单，请求会被拦截。
• 关键词过滤：如果设置了关键词，消息内容必须包含该关键词，否则发送会失败。
• 频率限制：自定义机器人有发送频率限制，频繁重试可能导致临时封禁，测试时注意间隔。
• Secret 混淆：一个群可能有多个机器人，确保代码中使用的 Secret 与当前 webhook 对应。

参考来源

• 钉钉开放平台，自定义机器人接入指南，https://open.dingtalk.com/document/robots/custom-robot-access
• 钉钉开放平台，群机器人接口文档，https://open.dingtalk.com/document/orgapp/group-robot