Webhook 订阅

创建和管理 webhook 订阅，用于事件驱动的代理激活，或直接推送通知（零 LLM 成本）。当用户希望外部服务触发代理运行或将通知推送到聊天时使用。

技能元数据

来源	捆绑（默认安装）
路径	skills/devops/webhook-subscriptions
版本	1.1.0
标签	webhook, events, automation, integrations, notifications, push

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Webhook 订阅

创建动态 webhook 订阅，以便外部服务（GitHub、GitLab、Stripe、CI/CD、IoT 传感器、监控工具）可以通过向 URL 发送 POST 请求来触发 Hermes 代理运行。

设置（必须首先执行）

在创建订阅之前，必须启用 webhook 平台。检查方法如下：

hermes webhook list

如果显示“Webhook platform is not enabled”（Webhook 平台未启用），请进行设置：

选项 1：设置向导

hermes gateway setup

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

选项 2：手动配置

添加到 ~/.hermes/config.yaml：

platforms:
  webhook:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8644
      secret: "generate-a-strong-secret-here"

选项 3：环境变量

添加到 ~/.hermes/.env：

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644
WEBHOOK_SECRET=generate-a-strong-secret-here

配置完成后，启动（或重启）网关：

hermes gateway run
# Or if using systemd:
systemctl --user restart hermes-gateway

验证其是否正在运行：

curl http://localhost:8644/health

命令

所有管理操作均通过 hermes webhook CLI 命令进行：

创建订阅

hermes webhook subscribe <name> \
  --prompt "Prompt template with {payload.fields}" \
  --events "event1,event2" \
  --description "What this does" \
  --skills "skill1,skill2" \
  --deliver telegram \
  --deliver-chat-id "12345" \
  --secret "optional-custom-secret"

返回 webhook URL 和 HMAC 密钥。用户需配置其服务向该 URL 发送 POST 请求。

列出订阅

hermes webhook list

删除订阅

hermes webhook remove <name>

测试订阅

hermes webhook test <name>
hermes webhook test <name> --payload '{"key": "value"}'

提示模板

提示支持使用 {dot.notation} 访问嵌套的负载字段：

• {issue.title} — GitHub issue 标题
• {pull_request.user.login} — PR 作者
• {data.object.amount} — Stripe 支付金额
• {sensor.temperature} — IoT 传感器读数

如果未指定提示，完整的 JSON 负载将被转储到代理提示中。

常见模式

GitHub：新 Issue

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
  --deliver telegram \
  --deliver-chat-id "-100123456789"

然后在 GitHub 仓库的 Settings → Webhooks → Add webhook 中：

• Payload URL：返回的 webhook_url
• Content type：application/json
• Secret：返回的 secret
• Events：“Issues”

GitHub：PR 审查

hermes webhook subscribe github-prs \
  --events "pull_request" \
  --prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
  --skills "github-code-review" \
  --deliver github_comment

Stripe：支付事件

hermes webhook subscribe stripe-payments \
  --events "payment_intent.succeeded,payment_intent.payment_failed" \
  --prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
  --deliver telegram \
  --deliver-chat-id "-100123456789"

CI/CD：构建通知

hermes webhook subscribe ci-builds \
  --events "pipeline" \
  --prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
  --deliver discord \
  --deliver-chat-id "1234567890"

通用监控警报

hermes webhook subscribe alerts \
  --prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
  --deliver origin

直接交付（无代理，零 LLM 成本）

对于只需将通知推送给用户聊天场景——无需推理，无需代理循环——添加 --deliver-only。渲染后的 --prompt 模板将成为字面消息正文，并直接分派到目标适配器。

适用于以下场景：

• 外部服务推送通知（Supabase/Firebase webhook → Telegram）
• 需要原样转发的监控警报
• 代理间 ping，即一个代理向另一个代理的用户传达信息
• 任何 LLM 往返会造成浪费的 webhook

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"

成功交付时 POST 返回 200 OK，目标失败时返回 502——因此上游服务可以智能重试。HMAC 认证、速率限制和幂等性仍然适用。

要求 --deliver 为真实目标（telegram、discord、slack、github_comment 等）——--deliver log 会被拒绝，因为仅日志的直接交付毫无意义。

安全性

• 每个订阅都会获得一个自动生成的 HMAC-SHA256 密钥（或使用 --secret 提供自定义密钥）
• Webhook 适配器会验证每个传入 POST 请求的签名
• config.yaml 中的静态路由不能被动态订阅覆盖
• 订阅持久化存储于 ~/.hermes/webhook_subscriptions.json

工作原理

1. hermes webhook subscribe 写入 ~/.hermes/webhook_subscriptions.json
2. Webhook 适配器在每个传入请求时热重载此文件（基于 mtime 门控，开销可忽略不计）
3. 当收到匹配路由的 POST 请求时，适配器格式化提示并触发代理运行
4. 代理的响应被交付到配置的目标（Telegram、Discord、GitHub 评论等）

故障排除

如果 webhook 无法工作：

1. 网关是否在运行？ 使用 systemctl --user status hermes-gateway 或 ps aux | grep gateway 进行检查
2. Webhook 服务器是否在监听？ curl http://localhost:8644/health 应返回 {"status": "ok"}
3. 检查网关日志： grep webhook ~/.hermes/logs/gateway.log | tail -20
4. 签名不匹配？ 验证服务中的密钥是否与 hermes webhook list 中的密钥一致。GitHub 发送 X-Hub-Signature-256，GitLab 发送 X-Gitlab-Token。
5. 防火墙/NAT 问题？ Webhook URL 必须可从服务访问。对于本地开发，请使用隧道工具（ngrok、cloudflared）。
6. 事件类型错误？ 检查 --events 过滤器是否与服务发送的内容匹配。使用 hermes webhook test <name> 验证路由是否正常工作。