webhook-subscriptions

Webhook サブスクリプション

動的な Webhook サブスクリプションを作成し、外部サービス（GitHub、GitLab、Stripe、CI/CD、IoT センサー、監視ツール）から URL にイベントを POST して、Hermes エージェントの実行をトリガーできます。

セットアップ（最初に必須）

サブスクリプションを作成する前に、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 ペイロード全体がエージェントのプロンプトに出力されます。

よくあるパターン

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> を使用して、ルートが機能することを確認します。