Webhooks

通过 Webhook 接收来自外部服务（如 GitHub、GitLab、JIRA、Stripe 等）的事件，并自动触发 Hermes Agent 的运行。Webhook 适配器会运行一个 HTTP 服务器，接收 POST 请求，验证 HMAC 签名，将请求体转换为 Agent 提示词（prompt），并将响应结果返回给源系统或配置的其他平台。

Agent 处理事件后，可执行以下操作：在 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        # default
WEBHOOK_SECRET=your-global-secret

验证服务器

网关启动后：

curl http://localhost:8644/health

预期响应：

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

配置路由

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

路由属性

属性	是否必需	描述
`events`	否	要接受的事件类型列表（例如 `["pull_request"]`）。若为空，则接受所有事件。事件类型从 payload 中的 `X-GitHub-Event`、`X-GitLab-Event` 或 `event_type` 读取。
`secret`	是	用于签名验证的 HMAC 密钥。若路由未设置，则回退到全局 `secret`。仅在测试时设为 `"INSECURE_NO_AUTH"`（跳过验证）。
`prompt`	否	使用点号表示法访问 payload 的模板字符串（例如 `{pull_request.title}`）。若省略，则将完整 JSON payload 作为提示词输入。
`skills`	否	为本次 Agent 运行加载的技能名称列表。
`deliver`	否	响应发送目标：`github_comment`、`telegram`、`discord`、`slack`、`signal`、`sms`、`whatsapp`、`matrix`、`mattermost`、`homeassistant`、`email`、`dingtalk`、`feishu`、`wecom`、`weixin`、`bluebubbles` 或 `log`（默认）。
`deliver_extra`	否	额外交付配置 —— 键取决于 `deliver` 类型（例如 `repo`、`pr_number`、`chat_id`）。值支持与 `prompt` 相同的 `{dot.notation}` 模板。

完整示例

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {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: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          deliver: "telegram"

提示词模板

提示词使用点号表示法访问 Webhook payload 中的嵌套字段：

{pull_request.title} 解析为 payload["pull_request"]["title"]
{repository.full_name} 解析为 payload["repository"]["full_name"]
{__raw__} — 特殊标记，将 整个 payload 以缩进格式输出为 JSON（截断至 4000 字符）。适用于监控告警或通用 Webhook 场景，此时 Agent 需要完整上下文。
缺失的键将保留为字面量 {key} 字符串（不报错）
嵌套的字典和列表会被 JSON 序列化，并在 2000 字符处截断

你可以在模板中混合使用 {__raw__} 和普通模板变量：

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

如果某个路由未配置 prompt 模板，则整个 payload 会以缩进 JSON 格式输出（截断至 4000 字符）。

相同的点号表示法也适用于 deliver_extra 的值。

论坛主题交付

当将 Webhook 响应交付至 Telegram 时，可通过在 deliver_extra 中包含 message_thread_id（或 thread_id）来指定特定论坛主题：

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

若 chat_id 未在 deliver_extra 中提供，交付将回退至目标平台配置的主频道。

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. 测试

在仓库中打开一个拉取请求。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: |
            Review this merge request:
            Project: {project.path_with_namespace}
            MR !{object_attributes.iid}: {object_attributes.title}
            Author: {object_attributes.last_commit.author.name}
            URL: {object_attributes.url}
            Action: {object_attributes.action}
          deliver: "log"

交付选项

deliver 字段控制 Agent 处理完 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`	将响应路由至 DingTalk。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。
`feishu`	将响应路由至 Feishu/Lark。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。
`wecom`	将响应路由至 WeCom。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。
`weixin`	将响应路由至 Weixin（微信）。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。
`bluebubbles`	将响应路由至 BlueBubbles（iMessage）。使用主频道，或在 `deliver_extra` 中指定 `chat_id`。

对于跨平台交付，目标平台也必须在网关中启用并连接。若 deliver_extra 中未提供 chat_id，响应将发送至该平台配置的主频道。

动态订阅（CLI）

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

创建订阅

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
  --deliver telegram \
  --deliver-chat-id "-100123456789" \
  --description "Triage new GitHub issues"

该命令将返回 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 适配器会在每次请求到达时热加载此文件（基于修改时间，开销可忽略）
静态路由（来自 config.yaml）始终优先于同名的动态路由
动态订阅使用与静态路由相同的路由格式和功能（事件、提示模板、技能、交付方式）
无需重启网关 —— 订阅后立即生效

由代理驱动的订阅

当被 webhook-subscriptions 技能引导时，代理可通过终端工具创建订阅。例如，让代理“为 GitHub 问题设置 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" 来完全跳过验证。

速率限制

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

platforms:
  webhook:
    extra:
      rate_limit: 60  # requests per minute

超过限制的请求将返回 429 Too Many Requests 响应。

幂等性

交付 ID（来自 X-GitHub-Delivery、X-Request-ID 或时间戳回退）会被缓存 1 小时。重复交付（如 Webhook 重试）将静默跳过，并返回 200 响应，防止代理重复运行。

请求体大小限制

超过 1 MB 的负载将在读取 body 之前就被拒绝。可进行如下配置：

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

提示注入风险

warning

Webhook 负载包含攻击者可控的数据 —— PR 标题、提交信息、问题描述等均可能包含恶意指令。当网关暴露于互联网时，请务必在沙盒环境（Docker、虚拟机）中运行。建议使用 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 密钥（当路由未指定自身密钥时作为备用）	(无)

快速入门​

配置设置​

通过设置向导​

通过环境变量​

验证服务器​

配置路由​

路由属性​

完整示例​

提示词模板​

论坛主题交付​

GitHub PR 审查（逐步指南）​

1. 在 GitHub 中创建 Webhook​

2. 添加路由配置​

3. 确保 gh CLI 已认证​

4. 测试​

GitLab Webhook 设置​

1. 在 GitLab 中创建 Webhook​

2. 添加路由配置​

交付选项​

动态订阅（CLI）​

创建订阅​

列出订阅​

删除订阅​

测试订阅​

动态订阅的工作原理​

由代理驱动的订阅​

安全性​

HMAC 签名验证​

密钥为必填项​

速率限制​

幂等性​

请求体大小限制​

提示注入风险​

故障排查​

Webhook 未送达​

签名验证失败​

事件被忽略​

代理无响应​

重复响应​

gh CLI 错误（GitHub 评论交付）​

环境变量​

快速入门

配置设置

通过设置向导

通过环境变量

验证服务器

配置路由

路由属性

完整示例

提示词模板

论坛主题交付

GitHub PR 审查（逐步指南）

1. 在 GitHub 中创建 Webhook

2. 添加路由配置

3. 确保 `gh` CLI 已认证

4. 测试

GitLab Webhook 设置

1. 在 GitLab 中创建 Webhook

2. 添加路由配置

交付选项

动态订阅（CLI）

创建订阅

列出订阅

删除订阅

测试订阅

动态订阅的工作原理

由代理驱动的订阅

安全性

HMAC 签名验证

密钥为必填项

速率限制

幂等性

请求体大小限制

提示注入风险

故障排查

Webhook 未送达

签名验证失败

事件被忽略

代理无响应

重复响应

`gh` CLI 错误（GitHub 评论交付）

环境变量