Webhooks — あらゆるイベントの入り口

こんなシーンを想像してみてください。開発者がGitHubでプルリクエストを開くと、数秒後にはあなたのAIエージェントがコードをレビューしてコメントを投稿している。あるいは、Stripeで決済が失敗したら、エージェントが自動的にTelegramでチームに通知する。これがWebhooksの魔法です。外部サービスがあなたのエージェントのドアをノックして、「ねえ、何か起きたよ、処理してくれない？」と伝えてくれるのです。

Webhooksとは？

Webhooksは、アプリケーションにとっての「呼び鈴」のようなものです。何かが変わっていないか常にチェックする（ポーリング）代わりに、ただ呼び鈴が鳴るのを待っていればいいのです。GitHub、GitLab、JIRA、Stripe、その他どんなサービスでも、あなたのWebhookエンドポイントにHTTP POSTリクエストを送ってくれば、Hermesエージェントが起きて、イベントを処理し、アクションを起こします。

一番いいところは？エージェントはさまざまな方法で応答できます。PRにコメントを投稿したり、TelegramやDiscordにメッセージを送ったり、後で確認するために結果をログに記録したりすることもできます。

クイックスタート

始めるのは驚くほど簡単です：

hermes gateway setup または環境変数で Webhookアダプターを有効化 する
config.yaml で ルートを定義 するか、hermes webhook subscribe で動的に作成する
サービスを http://your-server:8644/webhooks/<route-name> に 向ける

これだけです。あなたのエージェントはもう待機状態です。

ゲートウェイのセットアップ

Webhookを有効にする方法は2つあります。お好みの方を選んでください。

オプション1: セットアップウィザード

hermes gateway setup

プロンプトに従って、Webhookを有効にし、ポートを選択し、グローバルなHMACシークレットを設定します。ウィザードが面倒な設定をすべて代わりにやってくれます。

オプション2: 環境変数

~/.hermes/.env に以下の行を追加します：

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # デフォルト
WEBHOOK_SECRET=your-global-secret

ゲートウェイが起動したら、動作しているか確認しましょう：

curl http://localhost:8644/health

以下のようなレスポンスが返ってくるはずです：

{"status": "ok", "platform": "webhook"}

ルートの設定

ルートはWebhook処理の中心です。各ルートは、特定のソースからのイベントをエージェントがどう扱うかを指示します。これは、さまざまな種類の訪問者に対する個別の指示書のようなものです。

ルートごとに設定できる項目は以下の通りです：

プロパティ	説明
`events`	受け付けるイベントタイプ（例：`["pull_request"]`）。空にするとすべて受け付けます。
`secret`	署名検証用のHMACシークレット。テスト時のみ `"INSECURE_NO_AUTH"` を使用してください。
`profile`	このルートを実行できるプロファイル（マルチプレクシングで便利）。
`prompt`	`{pull_request.title}` のようなドット記法を使ったテンプレート文字列。省略するとJSONペイロード全体をそのまま渡します。
`filters`	エージェント実行前に不要なペイロードを無視するための宣言的条件。
`script`	テンプレート処理前にペイロードを変更できるフィルター／変換スクリプト。
`skills`	このエージェント実行でロードするスキル。
`toolsets`	エージェントが使用できるツール（デフォルトのWebhookツールセットを置き換えます）。
`deliver`	レスポンスの送信先：`github_comment`、`telegram`、`discord`、`slack`、`log` など。
`deliver_extra`	リポジトリ名やチャットIDなどの追加の配信詳細。
`deliver_only`	エージェントを完全にスキップして、レンダリングされたプロンプトをそのまま配信します。LLMコストゼロ！

実践的な例

実際の設定を見てみましょう。これはプルリクエストをレビューするルートです：

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

そして、誰かがメインブランチにプッシュしたときだけTelegram通知を送るルートはこちら：

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

スマートフィルタリング

filters 機能は特に便利です。プロバイダーは大量のイベントを送ってくることがよくありますが、あなたが気にするのはその一部だけです。フィルターを使えば、エージェントが起動する前にノイズを無視できます。条件に一致しないペイロードには、HTTP 200で丁寧に {"status":"ignored","reason":"filter"} と返します。無駄な計算も、不要なLLM呼び出しもありません。

直接配信モード

ここに賢いトリックがあります：deliver_only: true を設定すると、エージェントはまったく実行されません。レンダリングされたプロンプトテンプレートがそのまま配信されるメッセージになります。つまり、LLMコストゼロでサブ秒の配信が可能です。AIの推論を必要としない単純な通知に最適です。

セキュリティに関する注意

覚えておいてください：認証されているからといって、信頼できるとは限りません。Webhookからのペイロードフィールドは信頼できないデータです。プロンプトやテンプレートで使用するものは、常に検証してサニタイズしてください。エージェントはWebhookのコンテンツをユーザー入力と同じように扱うべきです。健全な懐疑心を持って。

まとめ

Webhooksは、あなたのHermesエージェントを、リアルタイムで世界に反応するレスポンシブなアシスタントに変えます。コードレビューの自動化、デプロイ通知の送信、複雑なイベント駆動型ワークフローの構築など、Webhookアダプターはほんの数行のYAMLでそれらすべてを可能にします。