Webhook Direct-Delivery Mode 详解

来源： Hermes Agent v0.11.0 Release Notes — PR #12473

发布日期： 2026年4月23日

核心概念

Webhook direct-delivery mode — Webhook 订阅现在可以将 payload 直接转发到平台聊天，无需经过 LLM Agent —— 零 LLM 消耗的推送通知，用于告警、运行检查和事件流。

一句话总结

Direct-Delivery Mode 就是 Webhook 的"纯路由"模式 —— Webhook 不再是"触发 AI 做事"的入口，而是变成了一个"不做任何判断、直接把消息搬到目标平台"的透明管道，省去 LLM 调用的费用和延迟。

普通模式 vs Direct-Delivery 模式对比

	普通 Webhook 模式	Direct-Delivery 模式
① 收到 Payload	✅	✅
② 签名验证	✅	✅
③ 构建 Prompt	将 payload 渲染成模板字符串	❌ 跳过
④ LLM Agent 处理	调用 LLM 分析 payload	❌ 跳过
⑤ 推送结果	Agent 的回复 → 目标平台	原始 payload 直接转发 → 目标平台
LLM 消耗	有（产生费用）	零
延迟	LLM 推理延迟（秒级）	毫秒级
适用场景	需要 AI 分析的复杂判断	纯通知、告警、事件流

普通模式流程

Webhook Payload → 签名验证 → 构建 Prompt → LLM Agent 处理 → 回复内容 → 目标平台

Direct-Delivery 模式流程

Webhook Payload → 签名验证 → 直接转发 → 目标平台
                                                        (全程无 LLM 参与)

工作原理

在普通模式中，_handle_webhook → 构建 prompt → handle_message(event) → Agent 处理 → send() 推送回复。

在 direct-delivery 模式中，webhook 收到 payload 后，绕过 handle_message（Agent 调用），直接将 payload（或经简单格式化）通过 deliver 指定的目标平台 adapter 发送出去。整个过程没有 LLM 参与。

关键代码逻辑（gateway/platforms/webhook.py）：

当路由未配置 prompt 时，系统跳过 Agent 处理流程
直接调用 deliver 指定平台的 adapter 进行消息推送
幂等性检查、速率限制、签名验证仍然生效

配置方式

config.yaml 路由配置

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        # ── 普通模式：LLM 分析后再推送 ──
        github-pr-review:
          events: ["pull_request"]
          secret: "github-secret"
          prompt: "Review this PR: {pull_request.title}"
          deliver: "telegram"
          deliver_extra:
            chat_id: "-1001234567890"

        # ── Direct-Delivery 模式：payload 直接转发，零 LLM ──
        uptime-alerts:
          events: ["alert"]
          secret: "uptime-secret"
          # 不配置 prompt → 不经过 Agent，直接转发 payload
          deliver: "telegram"
          deliver_extra:
            chat_id: "-1001234567890"

CLI 动态订阅

# 普通订阅（经过 Agent）
hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "New issue: {issue.title}" \
  --deliver telegram --deliver-chat-id "-100123456789"

# Direct-Delivery 订阅（绕过 Agent，直接推送原始 payload）
# 注意：不加 --prompt 参数即为 direct-delivery 模式
hermes webhook subscribe uptime-alerts \
  --events "alert" \
  --deliver telegram --deliver-chat-id "-100123456789"

适用场景分析

场景	推荐模式	原因
GitHub PR 需要 AI Code Review	普通模式	需要 LLM 分析代码
服务器宕机告警	Direct-Delivery	知道发生了什么，直接通知即可
定时任务执行结果	Direct-Delivery	结果已明确，无需再分析
支付成功/失败通知	Direct-Delivery	确定性事件，直接推送
CI/CD 构建结果通知	Direct-Delivery	构建成功/失败状态明确
需要 AI 总结的复杂事件	普通模式	LLM 提取关键信息、生成摘要
新 Issue 入库需要 AI 分类	普通模式	需要理解内容再判断

实际用例：网站监控告警

┌─────────────┐     ┌──────────────────┐     ┌────────────┐
│  监控服务    │────▶│  Hermes Webhook  │────▶│  Telegram  │
│ (UptimeKuma)│     │  Direct-Delivery │     │  告警通知  │
│  网站宕机    │     │  (零 LLM)        │     │  网站挂了! │
└─────────────┘     └──────────────────┘     └────────────┘

以前：网站宕机 → Webhook → LLM 分析 → "网站宕机了，建议检查XXX服务" → Telegram
现在：网站宕机 → Webhook → 直接转发 → Telegram（收到原始告警消息）

安全特性（仍然生效）

即使在 Direct-Delivery 模式下，以下安全机制依然有效：

特性	说明
HMAC 签名验证	GitHub (`X-Hub-Signature-256`)、GitLab (`X-Gitlab-Token`)、通用 (`X-Webhook-Signature`)
速率限制	每路由默认 30 请求/分钟，可配置 `rate_limit`
幂等性	1 小时内相同 `X-GitHub-Delivery` / `X-Request-ID` 的重复请求会被跳过
Body 大小限制	默认 1MB，可配置 `max_body_bytes`
Secret 必需	每个路由必须配置 HMAC secret