webhook-subscriptions

Webhook 订阅

创建动态 Webhook 订阅，让外部服务（GitHub、GitLab、Stripe、CI/CD、IoT 传感器、监控工具）可以通过向 URL 发送 POST 事件来触发 Hermes Agent 运行。

设置（必须先完成）

必须先启用 Webhook 平台，才能创建订阅。运行以下命令检查：

hermes webhook list

如果显示“Webhook platform is not enabled”，请进行设置：

选项 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 载荷会被写入 Agent 提示词。

常见用法

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

直接投递（不运行 Agent，不产生 LLM 费用）

如果你只想将通知推送到用户的聊天中，而不需要推理或 Agent 循环，请添加 --deliver-only。渲染后的 --prompt 模板会作为原样消息正文，直接发送给目标适配器。

适用于以下场景：

• 外部服务推送通知（Supabase/Firebase Webhook → Telegram）
• 需要原样转发的监控警报
• Agent 间的提示，即一个 Agent 告知另一个 Agent 的用户某些信息
• 任何调用大模型会徒增开销的 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 适配器会在每个传入请求时热重载此文件（仅在修改时间变化时检查，开销可忽略不计）
3. 收到与某个路由匹配的 POST 请求时，适配器会格式化提示词并触发 Agent 运行
4. Agent 的响应会发送到配置的目标（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> 验证路由是否正常工作。