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> 驗證路由是否正常工作。