Webhook 通知

Webhook 通知系统让你能够及时接收 Claude Code Hub 的关键事件通知。当供应商熔断、成本超限或定时报表生成时，系统会自动将消息推送到你配置的渠道，帮助你实时掌握系统运行状态。

支持的推送渠道

系统支持五种推送渠道，覆盖主流的企业协作工具：

通知事件类型

系统支持三种通知事件，分别对应不同的业务场景。

熔断器告警

当供应商连续失败达到阈值触发熔断时，系统会发送告警通知。

触发条件：

• 供应商端点连续失败次数达到熔断阈值（默认 5 次）

消息内容：

• 供应商名称和 ID
• 连续失败次数
• 预计恢复时间
• 最后一次错误信息

防重复机制： 为避免短时间内重复发送相同的熔断告警，系统实现了 5 分钟去重机制。同一供应商的熔断告警在 5 分钟内只会发送一次。

成本预警

当用户或供应商的消费达到配额阈值时触发预警。

触发条件：

• 5 小时消费达到限额阈值
• 周消费达到限额阈值
• 月消费达到限额阈值

检查间隔： 成本预警按配置的间隔定期检查，默认每 60 分钟检查一次。你可以在通知设置中调整检查间隔。

消息内容：

• 目标类型（用户/供应商）和名称
• 当前消费金额和配额限制
• 使用比例（带颜色指示器）
• 剩余额度和统计周期

使用比例指示器：

• 红色：使用比例 >= 90%
• 黄色：使用比例 >= 80%
• 绿色：使用比例 < 80%

每日消费排行榜

定时发送过去 24 小时的用户消费排行榜。

触发条件：

• 按配置的 Cron 表达式定时触发（默认每天 09:00）

显示数量： 排行榜默认显示前 5 名用户，你可以在通知设置中调整显示数量（dailyLeaderboardTopN）。

消息内容：

• 统计日期
• 排名列表（显示前 N 名）
• 每个用户的消费金额、请求次数、Token 使用量
• 总请求数和总消费金额

配置模式

Webhook 通知系统支持两种配置模式，以适应不同的使用场景。

旧版模式（单 URL）

旧版模式为每个通知类型配置一个 Webhook URL，系统自动从 URL 检测平台类型。

适用场景：

• 只需要向单一渠道发送通知
• 使用企业微信或飞书（支持自动识别）

配置方式： 在「设置 → 通知设置」页面，直接填写各通知类型对应的 Webhook URL。

新模式（多目标管理）

新模式支持独立管理多个推送目标，并将通知类型与目标进行灵活绑定。

适用场景：

• 需要向多个渠道同时发送通知
• 需要为不同通知类型配置不同的目标
• 需要使用 Telegram 或自定义 Webhook

自动切换机制： 当你创建第一个 Webhook 目标时，系统会自动从旧版模式切换到新模式。旧版的 URL 配置仍然保留，但新的通知将使用目标绑定机制发送。

全局开关

通知系统有一个全局开关控制所有通知功能：

• 启用通知（enabled）：控制整个通知系统的启用/禁用状态，默认关闭
• 使用旧版模式（useLegacyMode）：控制使用旧版单 URL 模式还是新模式，默认开启旧版模式

当全局开关关闭时，所有通知都不会发送，已存在的定时任务也会被清除。

配置 Webhook 目标

企业微信

1. 在企业微信群中添加群机器人
2. 复制机器人的 Webhook URL
3. 在 Claude Code Hub 中创建目标，选择「企业微信」类型
4. 粘贴 Webhook URL

URL 格式：

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx

飞书

1. 在飞书群中添加自定义机器人
2. 复制机器人的 Webhook URL
3. 在 Claude Code Hub 中创建目标，选择「飞书」类型
4. 粘贴 Webhook URL

URL 格式：

https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx

钉钉

1. 在钉钉群中添加机器人
2. 复制机器人的 Webhook URL
3. 在 Claude Code Hub 中创建目标，选择「钉钉」类型
4. 粘贴 Webhook URL

加签安全（可选）： 如果启用了加签安全设置，需要填写加签密钥。系统会自动计算时间戳和签名。

Telegram

1. 在 Telegram 中联系 @BotFather 创建 Bot
2. 获取 Bot Token
3. 获取目标 Chat ID（可以是用户 ID 或群组 ID）
4. 在 Claude Code Hub 中创建目标，选择「Telegram」类型
5. 填写 Bot Token 和 Chat ID

获取 Chat ID 的方法：

• 私聊：使用 @userinfobot
• 群组：将 Bot 加入群组后，访问 https://api.telegram.org/bot<TOKEN>/getUpdates 查看

自定义 Webhook

自定义 Webhook 允许你定义自己的消息格式，适用于集成到内部系统或第三方平台。

配置参数：

• Webhook URL：接收端点地址
• 自定义模板：JSON 对象，支持变量占位符
• 自定义请求头：可选的 HTTP 请求头

默认模板结构： 系统为每种通知类型提供默认模板：

// 熔断器告警默认模板
{
  "title": "{{title}}",
  "provider": "{{provider_name}}",
  "providerId": "{{provider_id}}",
  "failureCount": "{{failure_count}}",
  "retryAt": "{{retry_at}}",
  "error": "{{last_error}}"
}

// 每日排行榜默认模板
{
  "title": "{{title}}",
  "date": "{{date}}",
  "totalRequests": "{{total_requests}}",
  "totalCost": "{{total_cost}}",
  "entries": "{{entries_json}}"
}

// 成本预警默认模板
{
  "title": "{{title}}",
  "targetType": "{{target_type}}",
  "targetName": "{{target_name}}",
  "currentCost": "{{current_cost}}",
  "quotaLimit": "{{quota_limit}}",
  "usagePercent": "{{usage_percent}}"
}

模板变量参考：

通用变量（所有通知类型可用）：

熔断器告警专用变量：

每日排行榜专用变量：

成本预警专用变量：

绑定通知类型

创建 Webhook 目标后，你需要将通知类型与目标进行绑定。

绑定配置：

• 通知类型：选择要绑定的通知事件
• 目标：选择已创建的 Webhook 目标
• 启用状态：控制该绑定是否生效

定时配置（可选）： 对于每日排行榜和成本预警，你可以在绑定级别覆盖定时设置：

• Cron 表达式：自定义调度时间
• 时区：指定 Cron 表达式的时区

模板覆盖（可选）： 对于自定义 Webhook 类型，你可以在绑定级别配置模板覆盖，实现更灵活的消息定制。

时区处理

系统支持多级时区配置，优先级从高到低：

1. 绑定级别时区：在通知绑定中配置的 scheduleTimezone
2. 系统时区：从系统设置中解析的时区
3. UTC：默认回退时区

时区用于：

• 定时通知的调度（如每日排行榜）
• 消息中的时间格式化显示
• Cron 表达式的解释

代理配置

每个 Webhook 目标可以独立配置代理，支持 HTTP/HTTPS/SOCKS5 代理。

配置参数：

• 代理 URL：代理服务器地址
• 降级策略：代理失败时是否尝试直连

当配置了代理且启用降级策略时，如果代理发送失败，系统会自动尝试直连发送。

重试机制

Webhook 通知系统实现了多层重试机制，确保消息可靠送达。

发送器级别重试

每个 Webhook 发送器内部实现了指数退避重试：

• 最大重试次数：3 次
• 基础延迟：1000 毫秒
• 延迟序列：1000ms → 2000ms → 4000ms

队列级别重试

通知队列（基于 Bull）配置了独立的重试策略：

• 最大重试次数：3 次
• 首次重试延迟：1 分钟
• 退避类型：指数退避（60s → 120s → 240s）

这意味着单条消息最多可能尝试 12 次（首次尝试 + 3 次发送器重试 = 4 次，再乘以 3 次队列重试）。

测试与监控

连通性测试

你可以随时测试 Webhook 目标的连通性：

1. 在目标列表中找到要测试的目标
2. 点击「测试」按钮
3. 系统会发送一条测试消息
4. 查看测试结果和响应延迟

测试消息使用与真实通知相同的渲染流程，确保测试结果准确反映实际发送情况。

状态展示

每个 Webhook 目标显示以下状态信息：

• 最后测试时间
• 最后测试结果（成功/失败）
• 响应延迟（毫秒）
• 详细的测试结果 JSON（包含错误信息）

安全考虑

签名验证

钉钉 Webhook 支持加签安全机制：

• 使用 HMAC-SHA256 算法
• 基于时间戳和密钥生成签名
• 防止请求被篡改或重放

敏感信息处理

• Bot Token、加签密钥等敏感信息在数据库中存储
• 日志中不记录敏感信息
• 前端界面中敏感字段使用密码输入框

权限控制

所有 Webhook 管理操作需要管理员权限。普通用户无法查看或修改 Webhook 配置。

故障排查

消息未收到

检查清单：

1. 确认 Webhook 目标已启用
2. 确认通知绑定已启用
3. 确认通知类型的全局开关已打开
4. 测试 Webhook 连通性
5. 查看系统日志中的错误信息

测试失败

常见原因：

• URL 格式错误
• 网络连接问题
• 平台限制（如企业微信的 IP 白名单）
• 认证信息错误（如钉钉加签密钥）

查看日志

系统会记录详细的 Webhook 发送日志：

action: webhook_send          # 发送成功
action: webhook_send_failed   # 发送失败
action: notification_job_failed  # 队列任务失败
action: circuit_breaker_alert_suppressed  # 熔断告警被去重

最佳实践

多平台备份

为关键通知配置多个推送目标，避免单点故障。例如：

• 同时配置企业微信和飞书
• 重要告警额外配置 Telegram

合理设置阈值

成本预警阈值默认为 80%，你可以根据实际需求调整：

• 80%：早期预警，关注消费趋势
• 90%：紧急预警，需要立即处理

定期测试

建议定期测试 Webhook 连通性，特别是在以下情况后：

• 修改了 Webhook 配置
• 网络环境发生变化
• 平台侧更新了安全策略

使用代理的场景

在以下场景建议配置代理：

• 服务器位于内网，需要代理才能访问外网
• 需要通过特定出口 IP 发送请求（平台白名单要求）

相关文档

• 时区处理 - 了解系统时区配置
• 熔断器机制 - 了解熔断器工作原理
• 成本跟踪 - 了解消费统计机制