跳到主要内容

Webhooks

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

Agent 处理事件后，可以在 PR 上发布评论、向 Telegram/Discord 发送消息，或记录结果。

视频教程​

快速开始​

  1. 通过 hermes gateway setup 或环境变量启用
  2. 在 config.yaml 中定义路由，或使用 hermes webhook subscribe 动态创建路由
  3. 将您的服务指向 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否Agent 运行时加载的技能（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，则完全跳过 Agent —— 渲染后的 prompt 模板直接作为消息体投递。零 LLM Token 消耗，亚秒级投递。详见直接投递模式。需要 deliver 设置为真实目标（非 log）。

完整示例​

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 有效载荷中的嵌套字段：

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

可以将 {__raw__} 与普通模板变量混合使用：

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

如果路由未配置 prompt 模板，整个有效载荷将以缩进 JSON 格式写入（截断至 4000 个字符）。

deliver_extra 的值也支持相同的点号记法模板语法。

论坛话题投递​

向 Telegram 投递 Webhook 响应时，可以通过在 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"

如果 deliver_extra 中未提供 chat_id，投递将回退到目标平台配置的主频道。

GitHub PR 代码审查（步骤详解）​

本教程演示如何在每个 Pull Request 上自动触发代码审查。

1. 在 GitHub 中创建 Webhook​

  1. 进入您的仓库 → Settings → Webhooks → Add webhook
  2. 将 Payload URL 设置为 http://your-server:8644/webhooks/github-pr
  3. 将 Content type 设置为 application/json
  4. 将 Secret 设置为与路由配置匹配的值（例如 github-webhook-secret）
  5. 在 Which events? 下，选择 Let me select individual events 并勾选 Pull requests
  6. 点击 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​

  1. 进入您的项目 → Settings → Webhooks
  2. 将 URL 设置为 http://your-server:8644/webhooks/gitlab-mr
  3. 输入您的 Secret token
  4. 选择 Merge request events（以及其他需要的事件）
  5. 点击 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 将响应路由到短信。使用主频道，或在 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将响应路由到电子邮件。使用主频道，或在 deliver_extra 中指定 chat_id。
dingtalk将响应路由到钉钉。使用主频道，或在 deliver_extra 中指定 chat_id。
feishu将响应路由到飞书/Lark。使用主频道，或在 deliver_extra 中指定 chat_id。
wecom将响应路由到企业微信。使用主频道，或在 deliver_extra 中指定 chat_id。
weixin将响应路由到微信（Weixin）。使用主频道，或在 deliver_extra 中指定 chat_id。
bluebubbles将响应路由到 BlueBubbles（iMessage）。使用主频道，或在 deliver_extra 中指定 chat_id。

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

直接投递模式​

默认情况下，每个 Webhook POST 都会触发 Agent 运行 —— 有效载荷成为提示词，Agent 处理后投递响应。这会消耗每次事件的 LLM Token。

对于只需要推送纯通知的场景 —— 无需推理、无需 Agent 循环，只需投递消息 —— 可在路由上设置 deliver_only: true。渲染后的 prompt 模板直接作为消息体，适配器将其直接投递到配置的目标。

适用场景​

  • 外部服务推送 —— Supabase/Firebase Webhook 在数据库变更时触发 → 立即通过 Telegram 通知用户
  • 监控告警 —— Datadog/Grafana 告警 Webhook → 推送到 Discord 频道
  • Agent 间通知 —— Agent A 通知 Agent B 的用户一个长时间任务已完成
  • 后台任务完成 —— Cron 任务结束 → 推送结果到 Slack

优势：

  • 零 LLM Token —— Agent 从不被调用
  • 亚秒级投递 —— 单次适配器调用，无推理循环
  • 与 Agent 模式相同的安全性 —— 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: "🎉 New match: {match.user_name} matched with you!"
          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 "🎉 New match: {match.user_name} matched with you!" \
  --description "Antenna match notifications"

响应状态码​

状态码含义
200 OK投递成功。响应体：{"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."}
200 OK（status=duplicate）幂等性 TTL（1 小时）内重复的 X-GitHub-Delivery ID。不重复投递。
401 UnauthorizedHMAC 签名无效或缺失。
400 Bad RequestJSON 请求体格式错误。
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 字段被忽略（没有 Agent 运行，无法注入技能）。
  • 模板渲染使用与 Agent 模式相同的 {dot.notation} 语法，包括 {__raw__} 标记。
  • 幂等性使用相同的 X-GitHub-Delivery / X-Request-ID 请求头 —— 使用相同 ID 的重试返回 status=duplicate 且不重复投递。

动态订阅（CLI）​

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

创建订阅​

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 密钥。将您的服务配置为 POST 到该 URL。

列出订阅​

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 中的静态路由始终优先于同名的动态订阅
  • 动态订阅使用与静态路由相同的格式和功能（事件、提示词模板、技能、投递）
  • 无需重启网关 —— 订阅后立即生效

Agent 驱动的订阅​

Agent 可以在 webhook-subscriptions 技能的引导下，通过终端工具创建订阅。告诉 Agent "为 GitHub Issues 设置一个 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 响应，防止重复触发 Agent。

请求体大小限制​

超过 1 MB 的有效载荷在读取请求体之前即被拒绝。配置方式：

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

提示词注入风险​

注意

Webhook 有效载荷包含攻击者可控的数据 —— PR 标题、提交信息、Issue 描述等均可能包含恶意指令。暴露到公网时，请在沙箱环境（Docker、虚拟机）中运行网关。考虑使用 Docker 或 SSH 终端后端进行隔离。

故障排查​

Webhook 未到达​

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

签名验证失败​

  • 确认路由配置中的密钥与 Webhook 来源配置的密钥完全一致
  • 对于 GitHub，密钥基于 HMAC —— 检查 X-Hub-Signature-256
  • 对于 GitLab，密钥是明文 Token 匹配 —— 检查 X-Gitlab-Token
  • 检查网关日志中的 Invalid signature 警告

事件被忽略​

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

Agent 无响应​

  • 在前台运行网关查看日志：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 密钥（路由未指定密钥时用作回退）（无）