Webhooks

从外部服务（GitHub、GitLab、JIRA、Stripe 等）接收事件，并自动触发 Hermes 代理运行。webhook 适配器运行一个 HTTP 服务器，接受 POST 请求，验证 HMAC 签名，将负载转换为代理提示，并将响应路由回源或另一个已配置的平台。

代理处理事件，并可以通过在 PR 上发布评论、发送消息到 Telegram/Discord 或记录结果来响应。

视频教程

通过 hermes gateway setup 或环境变量启用
在 config.yaml 中定义路由，或使用 hermes webhook subscribe 动态创建
将您的服务指向 http://your-server:8644/webhooks/<route-name>

设置

启用 webhook 适配器有两种方式。

通过设置向导

hermes gateway setup

按照提示启用 webhook、设置端口和设置全局 HMAC 密钥。

通过环境变量

添加到 ~/.hermes/.env：

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # 默认
WEBHOOK_SECRET=your-global-secret

验证服务器

网关运行后：

curl http://localhost:8644/health

预期响应：

{"status": "ok", "platform": "webhook"}

配置路由

路由定义如何处理不同的 webhook 源。每个路由是 config.yaml 中 platforms.webhook.extra.routes 下的一个命名条目。

路由属性

属性	必填	描述
`events`	否	接受的事件类型列表（例如 `["pull_request"]`）。如果为空，接受所有事件。事件类型从 `X-GitHub-Event`、`X-GitLab-Event` 或负载中的 `event_type` 读取。
`secret`	是	用于签名验证的 HMAC 密钥。如果路由上未设置，则回退到全局 `secret`。仅用于测试时设置为 `"INSECURE_NO_AUTH"`（跳过验证）。
`prompt`	否	带点号表示法负载访问的模板字符串（例如 `{pull_request.title}`）。如果省略，完整 JSON 负载被转储到提示中。
`skills`	否	为代理运行加载的技能名称列表。
`deliver`	否	发送响应的目标：`github_comment`、`telegram`、`discord`、`slack`、`signal`、`sms`、`whatsapp`、`matrix`、`mattermost`、`homeassistant`、`email`、`dingtalk`、`feishu`、`wecom`、`weixin`、`bluebubbles`、`qqbot` 或 `log`（默认）。
`deliver_extra`	否	额外的投递配置——键取决于 `deliver` 类型（例如 `repo`、`pr_number`、`chat_id`）。值支持与 `prompt` 相同的 `{dot.notation}` 模板。
`deliver_only`	否	如果为 `true`，完全跳过代理——渲染后的 `prompt` 模板成为投递的字面消息。零 LLM 成本，亚秒级投递。请参见直接投递模式了解用例。需要 `deliver` 为真实目标（非 `log`）。

完整示例

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            审核此 Pull Request：
            仓库：{repository.full_name}
            PR #{number}：{pull_request.title}
            作者：{pull_request.user.login}
            URL：{pull_request.html_url}
            Diff URL：{pull_request.diff_url}
            操作：{action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"
        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "新推送至 {repository.full_name} 分支 {ref}：{head_commit.message}"
          deliver: "telegram"

提示模板

提示使用点号表示法访问 webhook 负载中的嵌套字段：

{pull_request.title} 解析为 payload["pull_request"]["title"]
{repository.full_name} 解析为 payload["repository"]["full_name"]
{__raw__} — 特殊令牌，将整个负载转储为缩进 JSON（截断至 4000 字符）。适用于监控告警或需要代理完整上下文的通用 webhook。
缺失的键保留为原义 {key} 字符串（无错误）
嵌套字典和列表被 JSON 序列化并截断至 2000 字符

您可以将 {__raw__} 与常规模板变量混合使用：

prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"

如果没有为路由配置 prompt 模板，整个负载会被转储为缩进 JSON（截断至 4000 字符）。

同样的点号表示法模板适用于 deliver_extra 值。

论坛话题投递

当将 webhook 响应投递到 Telegram 时，您可以通过在 deliver_extra 中包含 message_thread_id（或 thread_id）来定位特定的论坛话题：

webhooks:
  routes:
    alerts:
      events: ["alert"]
      prompt: "告警：{__raw__}"
      deliver: "telegram"
      deliver_extra:
        chat_id: "-1001234567890"
        message_thread_id: "42"

如果在 deliver_extra 中未提供 chat_id，投递会回退到目标平台配置的家聊。

GitHub PR 审查（分步指南）

此演练为每个 Pull Request 设置自动代码审查。

1. 在 GitHub 中创建 webhook

前往您的仓库 → Settings → Webhooks → Add webhook
设置 Payload URL 为 http://your-server:8644/webhooks/github-pr
设置 Content type 为 application/json
设置 Secret 以匹配您的路由配置（例如 github-webhook-secret）
在 Which events? 下，选择 Let me select individual events 并勾选 Pull requests
点击 Add webhook

2. 添加路由配置

将 github-pr 路由添加到您的 ~/.hermes/config.yaml，如上方示例所示。

3. 确保 `gh` CLI 已认证

github_comment 投递类型使用 GitHub CLI 发布评论：

gh auth login

4. 测试

在仓库上创建一个 Pull Request。Webhook 触发，Hermes 处理事件，并在 PR 上发布审查评论。

GitLab Webhook 设置

GitLab webhook 的工作方式类似，但使用不同的认证机制。GitLab 将密钥作为纯文本 X-Gitlab-Token 标头发送（精确字符串匹配，而非 HMAC）。

1. 在 GitLab 中创建 webhook

前往您的项目 → Settings → Webhooks
设置 URL 为 http://your-server:8644/webhooks/gitlab-mr
输入您的 Secret token
选择 Merge request events（以及您想要的任何其他事件）
点击 Add webhook

2. 添加路由配置

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        gitlab-mr:
          events: ["merge_request"]
          secret: "your-gitlab-secret-token"
          prompt: |
            审核此合并请求：
            项目：{project.path_with_namespace}
            MR !{object_attributes.iid}：{object_attributes.title}
            作者：{object_attributes.last_commit.author.name}
            URL：{object_attributes.url}
            操作：{object_attributes.action}
          deliver: "log"

投递选项

deliver 字段控制处理 webhook 事件后代理响应的去向。

投递类型	描述
`log`	将响应记录到网关日志输出。这是默认值，适用于测试。
`github_comment`	通过 `gh` CLI 将响应发布为 PR/issue 评论。需要 `deliver_extra.repo` 和 `deliver_extra.pr_number`。`gh` CLI 必须在网关主机上安装并认证（`gh auth login`）。
`telegram`	将响应路由到 Telegram。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`discord`	将响应路由到 Discord。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`slack`	将响应路由到 Slack。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`signal`	将响应路由到 Signal。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`sms`	通过 Twilio 将响应路由到 SMS。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`whatsapp`	将响应路由到 WhatsApp。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`matrix`	将响应路由到 Matrix。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`mattermost`	将响应路由到 Mattermost。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`homeassistant`	将响应路由到 Home Assistant。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`email`	将响应路由到 Email。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`dingtalk`	将响应路由到钉钉。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`feishu`	将响应路由到飞书/Lark。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`wecom`	将响应路由到企业微信。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`weixin`	将响应路由到微信。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。
`bluebubbles`	将响应路由到 BlueBubbles（iMessage）。使用家聊，或在 `deliver_extra` 中指定 `chat_id`。

对于跨平台投递，目标平台也必须在网关中启用并连接。如果在 deliver_extra 中未提供 chat_id，响应将发送到该平台配置的家聊。

直接投递模式

默认情况下，每个 webhook POST 都会触发一次代理运行——负载成为提示，代理处理它，代理的响应被投递。这会在每个事件上消耗 LLM 令牌。

对于您只想推送纯通知的用例——无需推理、无需代理循环，只需投递消息——在路由上设置 deliver_only: true。渲染后的 prompt 模板成为字面消息体，适配器直接将其分派到配置的投递目标。

何时使用直接投递

外部服务推送 — Supabase/Firebase webhook 在数据库变更时触发 → 即时通知 Telegram 中的用户
监控告警 — Datadog/Grafana 告警 webhook → 推送到 Discord 频道
代理间 ping — 代理 A 通知代理 B 的用户某个长时间运行的任务已完成
后台作业完成 — 定时任务完成 → 将结果发布到 Slack

优势：

零 LLM 令牌 — 从不调用代理
亚秒级投递 — 单次适配器调用，无推理循环
与代理模式相同的安全性 — HMAC 认证、速率限制、幂等性和正文大小限制仍然适用
同步响应 — POST 在投递成功后返回 200 OK，如果目标拒绝则返回 502，因此您的上游服务可以智能重试

示例：来自 Supabase 的 Telegram 推送

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-secret"
      routes:
        antenna-matches:
          secret: "antenna-webhook-secret"
          deliver: "telegram"
          deliver_only: true
          prompt: "🎉 新匹配：{match.user_name} 与您匹配了！"
          deliver_extra:
            chat_id: "{match.telegram_chat_id}"

您的 Supabase Edge Function 使用 HMAC-SHA256 签署负载并 POST 到 https://your-server:8644/webhooks/antenna-matches。Webhook 适配器验证签名，从负载渲染模板，投递到 Telegram，并返回 200 OK。

示例：通过 CLI 动态订阅

hermes webhook subscribe antenna-matches \
  --deliver telegram \
  --deliver-chat-id "123456789" \
  --deliver-only \
  --prompt "🎉 新匹配：{match.user_name} 与您匹配了！" \
  --description "Antenna 匹配通知"

响应码

状态	含义
`200 OK`	投递成功。正文：`{"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."}`
`200 OK`（status=duplicate）	重复的 `X-GitHub-Delivery` ID，在幂等性 TTL（1 小时）内。不重新投递。
`401 Unauthorized`	HMAC 签名无效或缺失。
`400 Bad Request`	JSON 正文格式错误。
`404 Not Found`	未知的路由名称。
`413 Payload Too Large`	正文超过 `max_body_bytes`。
`429 Too Many Requests`	路由速率限制超出。
`502 Bad Gateway`	目标适配器拒绝消息或抛出异常。错误记录在服务端；响应体为通用 `Delivery failed`，以避免泄露适配器内部信息。

配置陷阱

deliver_only: true 要求 deliver 为真实目标。deliver: log（或省略 deliver）在启动时被拒绝——适配器在发现配置错误的路由时会拒绝启动。
skills 字段在直接投递模式下被忽略（没有代理运行，因此没有地方注入技能）。
模板渲染使用与代理模式相同的 {dot.notation} 语法，包括 {__raw__} 令牌。
幂等性使用相同的 X-GitHub-Delivery / X-Request-ID 标头——使用相同 ID 的重试返回 status=duplicate，且不会重新投递。

动态订阅（CLI）

除了 config.yaml 中的静态路由，您还可以使用 hermes webhook CLI 命令动态创建 webhook 订阅。这在代理本身需要设置事件驱动触发器时特别有用。

创建订阅

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "新 issue #{issue.number}: {issue.title}\n作者: {issue.user.login}\n\n{issue.body}" \
  --deliver telegram \
  --deliver-chat-id "-100123456789" \
  --description "分类新的 GitHub issue"

这会返回 webhook URL 和一个自动生成的 HMAC 密钥。配置您的服务向该 URL 发送 POST。

列出订阅

hermes webhook list

删除订阅

hermes webhook remove github-issues

测试订阅

hermes webhook test github-issues
hermes webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'

动态订阅的工作原理

订阅存储在 ~/.hermes/webhook_subscriptions.json
Webhook 适配器在每个入站请求上热重载此文件（基于 mtime 门控，开销可忽略）
config.yaml 中的静态路由始终优先于同名的动态路由
动态订阅使用与静态路由相同的路由格式和能力（事件、提示模板、技能、投递）
无需网关重启——订阅后立即生效

代理驱动的订阅

代理可以通过终端工具在 webhook-subscriptions 技能的引导下创建订阅。让代理”为 GitHub issue 设置一个 webhook”，它会运行适当的 hermes webhook subscribe 命令。

安全

Webhook 适配器包含多层安全保护：

HMAC 签名验证

适配器使用每种来源的适当方法验证入站 webhook 签名：

GitHub：X-Hub-Signature-256 标头——以 sha256= 为前缀的 HMAC-SHA256 十六进制摘要
GitLab：X-Gitlab-Token 标头——纯文本密钥字符串匹配
通用：X-Webhook-Signature 标头——原始 HMAC-SHA256 十六进制摘要

如果配置了密钥但没有可识别的签名标头存在，请求将被拒绝。

密钥是必需的

每个路由必须有一个密钥——要么直接在路由上设置，要么从全局 secret 继承。没有密钥的路由会导致适配器在启动时失败并报错。仅用于开发/测试，您可以将密钥设置为 "INSECURE_NO_AUTH" 以完全跳过验证。

INSECURE_NO_AUTH 仅在网关绑定到回环主机（127.0.0.1、localhost、::1）时接受。如果与非回环绑定（如 0.0.0.0 或局域网 IP）组合，适配器拒绝启动——这可以防止意外在公共接口上暴露未经认证的端点。

速率限制

每个路由默认限制为每分钟 30 个请求（固定窗口）。全局配置：

platforms:
  webhook:
    extra:
      rate_limit: 60  # 每分钟请求数

超出限制的请求会收到 429 Too Many Requests 响应。

幂等性

投递 ID（来自 X-GitHub-Delivery、X-Request-ID 或时间戳回退）被缓存 1 小时。重复投递（例如 webhook 重试）被静默跳过，返回 200 响应，防止重复的代理运行。

正文大小限制

超过 1 MB 的负载在正文被读取之前就被拒绝。配置：

platforms:
  webhook:
    extra:
      max_body_bytes: 2097152  # 2 MB

提示注入风险

:::warning Webhook 负载包含攻击者可控制的数据——PR 标题、提交消息、issue 描述等都可能包含恶意指令。当暴露在互联网上时，在沙箱环境（Docker、VM）中运行网关。考虑使用 Docker 或 SSH 终端后端进行隔离。 :::

故障排查

Webhook 未到达

确认端口已暴露且可从 webhook 源访问
检查防火墙规则——端口 8644（或您配置的端口）必须开放
确认 URL 路径匹配：http://your-server:8644/webhooks/<route-name>
使用 /health 端点确认服务器正在运行

签名验证失败

确保路由配置中的密钥与 webhook 源中配置的密钥完全匹配
对于 GitHub，密钥基于 HMAC——检查 X-Hub-Signature-256
对于 GitLab，密钥是纯文本令牌匹配——检查 X-Gitlab-Token
检查网关日志中的 Invalid signature 警告

事件被忽略

检查事件类型是否在路由的 events 列表中
GitHub 事件使用诸如 pull_request、push、issues 之类的值（X-GitHub-Event 标头值）
GitLab 事件使用诸如 merge_request、push 之类的值（X-GitLab-Event 标头值）
如果 events 为空或未设置，所有事件都被接受

代理未响应

在前台运行网关以查看日志：hermes gateway run
检查提示模板是否正确渲染
确认投递目标已配置并连接

重复响应

幂等性缓存应防止此问题——检查 webhook 源是否发送了投递 ID 标头（X-GitHub-Delivery 或 X-Request-ID）
投递 ID 缓存 1 小时

`gh` CLI 错误（GitHub 评论投递）

在网关主机上运行 gh auth login
确保已认证的 GitHub 用户对仓库具有写权限
检查 gh 是否已安装且在 PATH 中

环境变量

变量	描述	默认值
`WEBHOOK_ENABLED`	启用 webhook 平台适配器	`false`
`WEBHOOK_PORT`	接收 webhook 的 HTTP 服务器端口	`8644`
`WEBHOOK_SECRET`	全局 HMAC 密钥（当路由未指定自己的密钥时用作回退）	（无）

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

Webhooks

Webhooks

视频教程

设置

通过设置向导

通过环境变量

验证服务器

配置路由

路由属性

完整示例

提示模板

论坛话题投递

GitHub PR 审查（分步指南）

1. 在 GitHub 中创建 webhook

2. 添加路由配置

3. 确保 gh CLI 已认证

4. 测试

GitLab Webhook 设置

1. 在 GitLab 中创建 webhook

2. 添加路由配置

投递选项

直接投递模式

何时使用直接投递

示例：来自 Supabase 的 Telegram 推送

示例：通过 CLI 动态订阅

响应码

配置陷阱

动态订阅（CLI）

创建订阅

列出订阅

删除订阅

测试订阅

动态订阅的工作原理

代理驱动的订阅

安全

HMAC 签名验证

密钥是必需的

速率限制

幂等性

正文大小限制

提示注入风险

故障排查

Webhook 未到达

签名验证失败

事件被忽略

代理未响应

重复响应

gh CLI 错误（GitHub 评论投递）

环境变量

关系图谱

目录

反向链接

3. 确保 `gh` CLI 已认证

`gh` CLI 错误（GitHub 评论投递）