企业微信外部群 Webhook 主动发送指南
一、适用场景与限制
适用：外部群（含微信好友）、固定群自动发通知、告警、日报、活动提醒
限制：
每个外部群最多 1 个机器人
限速：每分钟最多 20 条，超限返回 429
不能 @外部微信用户，只能 @企业成员或 @all
Webhook Key 泄露 = 任何人可向你的群发消息，务必保密
二、第一步：创建外部群机器人（PC 端操作）
打开企业微信 PC 端 → 进入目标外部群
右上角点 ... → 群机器人 → 添加机器人
填机器人名称（如 “订单通知助手”），可选填简介、头像
生成后立即复制 Webhook 地址，格式如下：
plaintext
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
关闭窗口后无法再次查看完整 Key，必须当场保存
三、支持的消息类型与 JSON 格式（直接复制）
1）文本消息（text，最简单）
json
{
"msgtype": "text",
"text": {
"content": "【系统通知】\n今日订单量：128单\n异常订单：3单",
"mentioned_list": ["@all"],
"mentioned_mobile_list": ["@all"]
}}mentioned_list：企业成员 userid 或@allmentioned_mobile_list：手机号或@all
2）Markdown（推荐，排版好看）
json
{
"msgtype": "markdown",
"markdown": {
"content": "### 📢 业务告警通知\n> **时间：**2026-04-27 22:00\n> **级别：**<font color='warning'>严重</font>\n> **内容：**支付接口响应超时\n> **建议：**请立即排查服务器状态\n[查看详情](https://your-domain.com/alert)"
}}支持：标题、加粗、引用、列表、链接、部分颜色（info/warning/comment）
3）图片（image）
json
{
"msgtype": "image",
"image": {
"base64": "图片base64编码",
"md5": "图片md5值"
}}4）图文卡片（news，最多 1 条）
json
{
"msgtype": "news",
"news": {
"articles": [
{
"title": "新品上线",
"description": "限时优惠，点击查看",
"url": "https://your-domain.com",
"picurl": "https://your-domain.com/cover.jpg"
}
]
}}四、代码调用示例（Python，直接运行）
基础发送函数
python
运行
import requestsimport json
WEBHOOK_URL = "你的Webhook地址"def send_wechat_msg(payload):
headers = {"Content-Type": "application/json"}
try:
resp = requests.post(WEBHOOK_URL, json=payload, timeout=10)
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"error": str(e)}# 1. 发文本text_payload = {
"msgtype": "text",
"text": {"content": "Hello 外部群！"}}print(send_wechat_msg(text_payload))# 2. 发Markdownmd_payload = {
"msgtype": "markdown",
"markdown": {"content": "### 每日日报\n- 新增用户：**100**\n- 营收：**¥50,000**"}}print(send_wechat_msg(md_payload))五、生产级最佳实践
Key 安全：
不要硬编码在代码里，用环境变量 / 配置中心
定期轮换机器人（删了重建，更新 Key）
频率控制：
批量发送时加sleep(3)，避免 429 限流
消息规范：
外部群避免营销感强内容，易被屏蔽
Markdown 控制在2000 字内，文本 2048 字节内
错误处理：
增加重试（3 次，间隔 2s）
记录日志，便于排查
六、常见错误与解决
401 无效 Key：Key 错误 / 已重置 / 机器人被删
429 请求超限：1 分钟 > 20 条，降频或分批
400 消息过长：缩短内容，拆分发送
无法 @外部成员：外部群限制，只能 @企业成员或 @all
七、vs 应用 API（简单对比）
Webhook（推荐）：10 分钟接入、无需企业权限、适合固定群通知
应用 API：需企业自建应用 + 客户联系权限、可批量发多群、开发复杂
