飞书自定义机器人

自定义机器人绑定到一个群聊，适合告警和业务播报。本文依据飞书开放平台资料整理，核验日期为 2026-09-08；未使用真实企业账号执行发送验证。

准备条件

有目标飞书群的机器人管理权限。
发送端能够通过 HTTPS 访问飞书 Webhook。
有服务器端密钥存储位置，不把 Webhook 放到浏览器代码中。

配置步骤

打开目标群的设置，在机器人入口添加“自定义机器人”。
填写名称和用途说明。
选择至少一种安全设置。优先使用签名校验，也可结合关键词或 IP 白名单。
保存后立即记录完整 Webhook；不要粘贴到工单、聊天或公开仓库。

凭据说明

字段	必需	说明
`WEBHOOK_URL`	是	创建机器人后生成的完整地址，视为密钥
`SIGNING_SECRET`	启用签名时	用于按平台规则生成时间戳签名
`KEYWORD`	启用关键词时	消息正文必须包含配置的关键词

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

未启用签名时，可先验证最小文本消息：

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"通知渠道连通性测试"}}'

const response = await fetch(process.env.WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msg_type: 'text',
    content: { text: '通知渠道连通性测试' },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

import os
import requests

response = requests.post(
    os.environ["WEBHOOK_URL"],
    json={"msg_type": "text", "content": {"text": "通知渠道连通性测试"}},
    timeout=15,
)
response.raise_for_status()
print(response.json())

启用签名后，需要按官方文档生成 timestamp 和 sign 并加入请求体，不能直接复用其他平台的 HMAC 格式。

验证结果

HTTP 成功不等于消息已到达。确认响应中的业务码表示成功，并在创建机器人的群聊中看到测试文本。随后再验证富文本或卡片。

安全建议

Webhook 和签名密钥只保存在服务器端。
日志中只记录脱敏后的机器人标识和平台请求 ID。
泄露后在群设置中删除或重新创建机器人，并替换发送端密钥。

常见问题

提示关键词不匹配：测试文本需要包含机器人安全设置中的关键词。

签名校验失败：检查服务器时间、时间戳单位、待签名字符串和 Base64 编码步骤。

请求成功但群里没有消息：确认机器人仍在目标群中，且请求发送到当前有效的 Webhook。

官方资料

飞书开放平台：在群组中添加自定义机器人