核心原理与风险

企业微信群机器人 Webhook 地址格式为https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=XXX，密钥直接包含在 URL 中。官方机制中，一旦后台点击重置密钥，旧key立即失效，请求返回错误码41002。不存在“旧密钥宽限期”，必须在失效前完成业务侧切换。

实操步骤

1. 准备新密钥与配置

不要直接重置旧机器人。进入企业微信管理后台，在原有群聊中新建一个机器人，复制新的 Webhook 地址。将新地址添加到配置中心或环境变量，建议采用列表形式支持多密钥。

# 环境变量示例 (支持多个地址，逗号分隔)
export WECOM_WEBHOOKS="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=OLD_KEY,https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=NEW_KEY"

2. 代码实现多密钥容错

为避免切换期间消息丢失，代码应支持故障转移（Failover）而非轮询。以下 Python 示例展示如何遍历密钥列表，直到发送成功：

import requests
import json
import os

webhooks = os.getenv("WECOM_WEBHOOKS").split(",")
payload = {"msgtype": "text", "text": {"content": "测试消息"}}

for url in webhooks:
    try:
        resp = requests.post(url, data=json.dumps(payload), timeout=5)
        res_json = resp.json()
        if res_json.get("errcode") == 0:
            print("发送成功")
            break
        else:
            print(f"发送失败：{res_json}")
    except Exception as e:
        print(f"请求异常：{e}")
        continue

3. 配置热加载或服务重启

更新配置后需使新配置生效。根据架构选择以下方式：

• Spring Cloud 体系：调用/actuator/refresh接口刷新配置。
• K8s 部署：更新 ConfigMap 后滚动重启 Pod。
• 传统进程：发送SIGHUP信号或手动重启服务。

验证方法

使用curl命令直接测试新 Webhook 地址，观察返回 JSON 中errcode是否为0。

curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=NEW_KEY" \
-H "Content-Type: application/json" \
-d '{"msgtype":"text","text":{"content":"密钥轮换测试"}}'

成功响应示例：

{"errcode":0,"errmsg":"ok"}

失败响应示例（密钥失效）：

{"errcode":41002,"errmsg":"invalid key"}

常见坑与监控

• 消息重复风险：切换期间若新旧密钥同时生效且代码逻辑为全量发送，会导致群内消息重复。建议采用“故障转移”逻辑，成功即止。
• 配置缓存：部分框架会缓存配置，更新后未清理缓存导致仍使用旧密钥。务必确认配置已加载。
• 监控指标：切换期间重点监控消息发送成功率及错误码分布。若出现大量41002，说明旧密钥已失效但业务仍在调用。
• 硬编码：密钥写死在代码里，修改后需要重新编译打包，延长停机时间。建议使用环境变量或配置中心管理。