WebHooker/docs/zh/api/overview.md

API 概览

WebHooker 通过 Hono 在 Cloudflare Workers 上提供 HTTP API。

基础 URL

https://your-worker.workers.dev

端点

方法	路径	鉴权	说明
GET	/health	无	健康检查
POST	/webhook	HMAC 签名	GitHub / Gitea / 自定义 webhook 接入（自动识别来源）
POST	/webhook/:groupId	分组 secret	分组级 webhook 入口（只触发该分组的路由）
POST	/discord/interactions	Ed25519 签名	Discord 交互（斜杠命令、按钮、modal）
POST	/telegram/webhook	Secret token	Telegram 更新（bot /gh 命令）
GET	/api/richheader	无	用于 Telegram 头像链接预览卡片的 Open Graph 页面
GET	/auth/github	无	启动 GitHub OAuth 流程
GET	/auth/github/callback	无	OAuth 回调
DELETE	/auth/token/:userId	无	撤销用户 Token
POST	/api/comment	Bearer Token	创建议题评论
POST	/api/merge	Bearer Token	合并拉取请求
POST	/api/close	Bearer Token	关闭拉取请求
POST	/api/react	Bearer Token	添加议题反应
GET	/admin	管理员会话	配置控制台页面
GET	/admin/api/routes	管理员会话	列出路由
PUT	/admin/api/routes	管理员会话	替换路由
GET	/admin/api/groups	管理员会话	列出分组（按权限过滤）
PUT	/admin/api/groups	管理员会话	替换分组（仅超级管理员）
GET	/admin/api/groups/:id/routes	管理员会话	列出某分组的路由
PUT	/admin/api/groups/:id/routes	管理员会话	替换某分组的路由
PUT	/admin/api/groups/:id/rename	管理员会话	重命名分组（owner）；路由/secret/邀请自动跟随
GET	/admin/api/me	管理员会话	当前会话信息
GET	/admin/api/logs	管理员会话	发送日志（按权限过滤）
GET	/admin/api/logs/:id	管理员会话	单条发送日志（按权限过滤）

管理控制台

参见配置 → Web 控制台了解设置方法。管理端点需要会话 Cookie，可通过 GET /admin/login（GitHub OAuth）获取；登录用户必须列在 ADMIN_USER_IDS 中。

• GET /admin — 提供配置控制台 HTML
• GET /admin/api/routes — 返回 { "routes": Route[] }
• PUT /admin/api/routes — 请求体为 { "routes": Route[] }；校验每条路由（id 格式、唯一 id、name、enabled、groupId、过滤器、可选的 discordRoleIds（身份组 id 字符串列表）、平台感知的 targets：Discord 需 target.channelId，Telegram 需 target.chatId）并持久化到 KV config:routes。返回 200 { ok, count } 或 400 { error } / 401 { error } / 403 { error }。

健康检查

GET /health

响应：

{
  "status": "ok"
}

Webhook 接入

POST /webhook

接受 GitHub webhook 载荷。需要有效的 X-Hub-Signature-256 头部。

请求头：

头部	必需	说明
X-Hub-Signature-256	是	HMAC-SHA256 签名
X-GitHub-Event	是	事件类型名称
X-GitHub-Delivery	否	唯一投递 ID（存在时用于去重）

请求体： GitHub webhook JSON 载荷（最大 1MB）。

响应：

{
  "ok": true
}

当 X-GitHub-Delivery 存在且同一投递在最近 5 分钟内已被处理时，Worker 返回 200 { "ok": true, "duplicate": true }，不再重复分发。

错误响应：

状态码	响应体	原因
401	{"error": "Invalid signature"}	签名验证失败
400	{"error": "Invalid event"}	缺少事件头或格式错误的请求体
413	{"error": "Request too large"}	请求体超过 1MB 限制

分组级 Webhook（POST /webhook/:groupId）

使用分组的 secret（KV tenant:{groupId}，在控制台「Webhook 入口」面板生成）验签，并且只分发到该分组的路由。支持 GitHub（X-Hub-Signature-256）、Gitea（X-Gitea-Signature）和自定义（X-WebHooker-Signature）发送方。分组不存在或未配置 secret 时返回 404。

自定义 Webhook

任意 JSON 载荷用 X-WebHooker-Signature: sha256=<hex>（对原始 body 的 HMAC-SHA256，使用分组或全局 secret）签名后即可成为 custom 事件。用 event: custom 过滤器的路由接收。载荷格式见配置 → 自定义 Webhook。

GitHub App 安装事件

installation webhook 事件（created 等）作为兜底会自动配置：按安装账号自动创建分组（inst-{installationId}，绑定 installationId）；或把 owners 匹配该账号的现有分组自动绑定到该安装。参见配置 → GitHub App 租户隔离。

主要流程是 App 的 Setup URL —— 将其设置为 {BASE_URL}/auth/github/install。用户安装 App 后浏览器会跳转到：

方法	路径	说明
GET	/auth/github/install	选择页：将安装绑定到新分组或登录用户拥有 owner 权限的已有分组
POST	/auth/github/install/bind	执行绑定（再次校验 owner 角色）并跳转 /admin?install=ok

错误格式

所有错误响应都遵循以下格式：

{
  "error": "错误的说明"
}