Webhook 插件（Yunzai）

适用于 Miao-Yunzai / TRSS-Yunzai（云崽 v3 系）：自定义 HTTP 接口（路径 / 请求方式 / 消息模板），收到请求后把消息转发到指定 QQ（私聊 / 群聊）。配置支持 Guoba-Plugin（锅巴）WebUI 编辑。

功能

能力	说明
自定义接口	每条规则任意 path，可同时配置多条
请求方式	每条规则可选 GET / POST / PUT / DELETE / PATCH / ANY
请求体转发	消息模板占位符渲染请求体（JSON / 表单 / 文本）后发送
指定 QQ 发送	每条规则可配多个目标：私聊（QQ 号）/ 群聊（群号）
转发形式发送	目标行首加「转发」即以**合并转发（聊天记录卡片）**发送（如 转发私聊 10001）
安全校验	全局 Token（X-Webhook-Token 请求头）+ 每条规则请求头校验（可选）
自定义响应	每条规则可自定义 HTTP 响应体（支持占位符）与状态码
测试命令	#webhook测试 <路径> 按模板向目标发测试消息

服务器命令（仅主人）：#webhook状态（服务与接口列表）、#webhook测试 <路径>、#webhook帮助。

安装

将 webhook-plugin 目录复制到 Yunzai 的 plugins/ 下，重启（或 #重启）生效。

配置（锅巴 WebUI，推荐）

锅巴面板 → 插件配置 → Webhook 插件。

服务配置

配置项	说明
enabled	总开关，关闭后所有接口返回 503
mode	挂载方式：auto（默认，优先复用云崽 HTTP 服务）/ standalone（独立端口）
host / port	独立服务监听地址与端口（默认 0.0.0.0:5788）
token	全局校验 Token：非空时请求头必须带 X-Webhook-Token: <token>

接口规则（可添加多条）

字段	说明
path	接口路径，如 /webhook/test（须以 / 开头）
method	GET / POST / PUT / DELETE / PATCH / ANY
secretHeaders	请求头校验，每行一个「头名: 值」（可留空）
template	消息模板（见下方占位符），可多行
targets	每行一个目标：私聊 <QQ号> / 群聊 <群号>（纯数字默认私聊）；行首加 转发 即以合并转发发送
responseBody / responseStatus	自定义响应体（支持占位符）与状态码（默认 200）

重复接口依次执行：允许配置多条「相同路径 + 相同请求方式」的规则，收到请求后按配置顺序依次执行（各自渲染模板、发各自目标）；HTTP 响应取第一条通过鉴权的规则。

锅巴保存后：接口增删改约 2 秒内生效；mode / port 等挂载方式变更立即生效，无需重启。

服务地址

• auto / express 模式：挂在云崽自带 HTTP 服务上（默认为端口 50831），外部访问 http://<服务器IP>:50831/webhook/test。
• standalone 模式：监听 host:port（如 0.0.0.0:5788）。
• 若云崽 server.yaml 配置了 auth，调用方还需带该鉴权头。

消息模板占位符

template 与 responseBody 通用，未命中的占位符保留原样：

占位符	说明
{body.字段}	请求体字段（点路径，数组用下标，如 {body.0.title}）
{query.参数}	GET 查询参数
{header.头名}	请求头（小写）
{method} {path} {ip} {time}	请求方式 / 接口路径 / 来源 IP / 接收时间
{raw} {json}	原始请求体 / 完整请求体（JSON 格式化）

template 留空时默认发送完整请求体（含接口、时间、来源 IP）。

示例（GitHub Webhook 推送）： template = 🔔 收到 GitHub 推送\n仓库：{body.repository.full_name}\n分支：{body.ref}\n提交者：{body.sender.login}\n摘要：{body.head_commit.message}

测试

curl -X POST http://<服务器IP>:50831/webhook/test \
  -H "Content-Type: application/json" \
  -d '{"title":"标题","content":"内容"}'

# 带全局 Token
curl -X POST http://<服务器IP>:50831/webhook/test \
  -H "X-Webhook-Token: 你的Token" -H "Content-Type: application/json" \
  -d '{"title":"标题"}'

# GET 接口
curl "http://<服务器IP>:50831/webhook/test?name=小明"

目录结构

webhook-plugin/
├── index.js              # 插件入口（HTTP 服务 / 模板渲染 / QQ 发送 / 命令）
├── guoba.support.js      # 锅巴 WebUI 配置支持（GSubForm 规则编辑）
├── components/config.js  # 共享配置模块（默认值 + config.json 读写，短 TTL 缓存）
├── config.def.js         # 默认配置模板（复制为 config.js 生效）
└── README.md

常见问题

• 接口访问不到？ 确认 mode 与端口映射：auto 用云崽 HTTP 端口（默认 50831）；检查云崽 server.yaml 的 auth 配置。
• 发送失败？ 私聊目标需为机器人好友；群聊目标需机器人已入群。日志中 [webhook-plugin] 会打印失败原因。
• 改了锅巴配置没生效？ 接口规则缓存约 2 秒；mode / port / enabled 保存即生效，仍无效则 #重启。
• {body.xxx} 没内容？ 确认请求 Content-Type 为 application/json（或表单），字段名写对；可用 {json} 先打印完整请求体排查。