Webhook 订阅

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

安装配置（必先完成）

创建订阅前必须启用 webhook 平台。检查：

hermes webhook list

如果显示"Webhook platform is not enabled"，设置它：

选项 1：设置向导

hermes gateway setup

按提示启用 webhooks、设置端口和全局 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

配置后启动（或重启）gateway：

hermes gateway run
# 或使用 systemd：
systemctl --user restart hermes-gateway

常用命令

创建订阅

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

列出订阅

hermes webhook list

移除订阅

hermes webhook remove 

测试订阅

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

Prompt 模板

Prompt 支持 {dot.notation} 访问嵌套 payload 字段：

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

常见模式

GitHub：新 issue

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

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"

直接投递（无 agent，零 LLM 成本）

对于只需推送通知到用户聊天——无需推理、无 agent 循环——添加 --deliver-only。渲染的 --prompt 模板成为字面消息体，直接分发到目标适配器。

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"

安全说明

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

常见问题

• Gateway 是否运行？用 systemctl --user status hermes-gateway 检查
• Webhook 服务器是否监听？curl http://localhost:8644/health 应返回 {"status": "ok"}
• 签名不匹配？验证你服务中的密钥与 hermes webhook list 中的一致
• 防火墙/NAT？Webhook URL 必须从服务可达。本地开发时使用隧道（ngrok、cloudflared）