feat(hub): add generic webhook notification channel - #1683
Open
renqiancheng wants to merge 4 commits into
Open
Conversation
Adds a WebhookChannel alongside the existing Telegram/ServerChan channels. It POSTs a small JSON payload (event/title/content/url/ sessionId) to a user-configured URL, so any self-hosted relay, serverless function, or third-party push gateway can receive HAPI notifications. This also covers hubs that cannot reach api.telegram.org / sctapi.ftqq.com directly: point the webhook at an endpoint the hub can reach and forward from there instead. Config follows the existing env > settings.json > default pattern: - HAPI_WEBHOOK_URL / webhookUrl - HAPI_WEBHOOK_KEY / webhookKey (sent as both a ?key= query param and an X-HAPI-Webhook-Key header for compatibility with existing webhook receivers) - HAPI_WEBHOOK_NOTIFICATION / webhookNotification (default true) - HAPI_WEBHOOK_BACKGROUND_ONLY / webhookBackgroundOnly (default false) Includes tests for the channel (mirrors serverchan/channel.test.ts) and for the new serverSettings.ts loading logic, plus doc updates in docs/guide/notifications.md, docs/guide/installation.md, and the settings JSON schema. AI-generated code disclosure: drafted with Claude (Anthropic), following the existing ServerChanChannel as the structural template.
① 请求最多等 10 秒，避免对方卡住时把后面的 Telegram 等通知也堵住。
② 不跟随跳转。以前 302 会把 key 和 X-HAPI-Webhook-Key 带到别的域名；现在直接当失败。
③ 报错里 不再带出完整 URL
④ 启动时就检查必须是 http/https，配成 ftp:// 或乱写会立刻失败，不用等到第一条通知。
⑤ Hub 启动日志改成和 Server酱 一样：只打 enabled / disabled / background-only，不打印 URL。
⑥ 文档纠正预期：这条通道是 中转：Hub 发的是 HAPI 自己的 {event, title, content, url, sessionId}。
⑦ 不把 HAPI_WEBHOOK_URL 直接指到 Bark / PushPlus / WxPusher。要自己写一个小中转，再转发给那些网关。
⑧ FAQ、quick-start、安装说明里补上了 Webhook。
⑨ 补了超时、跳转、非法 URL、hidden 连接仍发送、跨 namespace 不误抑制等用例。
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Findings
- [Major] 非法
settings.json值会静默移除鉴权或让禁用开关失效。 - [Major] Webhook 位于 Telegram 前且通知通道串行执行，故障端点会延迟现有 Telegram 通知。
- [Major] 对端错误响应正文进入 Hub 日志，可能泄露 key 并允许日志注入。
Summary
Review mode: initial
共 3 个 Major；具体证据与修复建议见 inline comments。
Testing
- Not run (automation)：按安全约束未执行 PR 代码。
- GitHub CI：
integration已通过；test与本次pr-review在审查时仍运行中。
HAPI Bot
1. 非法 settings.json 不再静默生效 非字符串 webhookKey（例如数字）启动时直接报错，不会变成 null 后无密钥继续发。"false" 这种字符串也不会再被当成开启；webhookNotification 必须是布尔值，和 webhookBackgroundOnly 一样。 2. Webhook 挪到 Telegram 后面 NotificationHub 仍是逐个 await。Webhook 卡住最多 10 秒时，Telegram 授权通知会先发出去，不再被拖住。 3. 对端响应正文不再进日志 非 2xx 只记录状态码和 statusText。正文里即使回显了 ?key=，也不会进 Hub 日志。
There was a problem hiding this comment.
Findings
- [Minor]
webhookUrl的 schema 仍接受非 HTTP(S) URI；具体证据与修复建议见 inline comment。
Summary
Review mode: follow-up after new commits
上一轮 3 个 Major 均已修复。完整复查最新 diff 后发现 1 个 Minor；未发现新的高置信度 correctness/security Major。
Testing
- Not run (automation)：按安全约束未执行 PR 代码。
- GitHub CI：
integration已通过；test在提交审查时仍运行中。
HAPI Bot
…p:// 这类会直接标红，不会拖到 Hub 启动才失败。
There was a problem hiding this comment.
Findings
- 未发现需要报告的高置信度问题。
Summary
Review mode: follow-up after new commits
本次新提交仅为 docs/public/schemas/settings.schema.json:75 增加 HTTP(S) pattern；上一轮 Minor 已修复。重新完整复查最新 PR diff 后，未发现新的 Blocker/Major/Minor/Nit。残余风险主要是当前自动化测试尚未完成。
Testing
- Not run (automation)：按安全约束未执行 PR 代码。
- GitHub CI：
integration已通过；test在提交审查时仍运行中。
HAPI Bot
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hub 现有的 Telegram / Server酱 通道，在部分网络下到不了 api.telegram.org / sctapi.ftqq.com。这次加了一条通用 Webhook 通道：Hub 把通知 POST 到用户自己配的 HTTP(S) 地址，由对方再转发。自建中转、Serverless、Worker 都可以接。
需要说清楚：这条通道发的是 HAPI 自己的 JSON（event / title / content / url / sessionId），不是 Bark / PushPlus / WxPusher 的协议。直接把 HAPI_WEBHOOK_URL 指过去，中间可能要自己写一层转发。
配置方式和现有通道一样，env > settings.json > default：
实现上收紧了几处，避免这条通道拖累别的通知或把密钥带出去：
文档（notifications / installation / FAQ / quick-start）和 settings schema 已同步。测试覆盖了通道行为、配置加载，以及超时、跳转、非法 URL、hidden 连接仍发送、跨 namespace 不误抑制等用例。