n8n → Hermes：API呼び出しかイベントwebhookかを選ぶ

n8nは、イベントの受信、フィールドの検証、API呼び出し、人の判断待ち、結果の書き込みといった、予測可能な自動化を得意とします。Hermes Agentは、次のステップに解釈が必要な場合に役立ちます。たとえば文章のトリアージ、返信の下書き、ツールを使った調査、文脈に応じた「緊急」の判断などです。

明確なパターンは2つあり、それぞれ契約が異なります。n8nがエージェントの結果を検証、保存、承認、または送信する必要があるなら、Hermes APIサーバーを呼び出します。n8nがイベントを送出し、その結果をHermesから設定済みのSlack、Telegram、GitHub、メール、またはほかの対応先へ配信するなら、webhookアダプターを呼び出します。

Hermes APIサーバーの公式ドキュメント、webhookの公式ドキュメント、NousResearchリポジトリーを参照してください。ここではHermes専用のn8nノードは一次資料に記載されておらず、n8nの汎用HTTP Requestノードを使います。

汎用のn8n送信元にはHermes V2 HMAC契約を使ってください。ほかのプロバイダーでは、GitHubの署名やGitLabのトークンなど、アダプター固有の認証を使う場合があります。すべてのルートに、ドキュメントで指定されたシークレットが必要です。INSECURE_NO_AUTHはループバックでのテスト専用です。現行のHermesは、非ループバックアドレスへバインドした状態でこの設定を使うと起動を拒否します。

引き継ぐ場合と引き継がない場合

n8nに残す処理

• スキーマ検証と機密情報の削除
• 冪等性キーと重複排除（冪等性と人によるゲート）
• 明示的な認証情報を使うCRM、メール、Slackコネクター
• 外部送信前の人による承認キュー
• cronとwebhookトリガー

Hermesへ渡す処理

• 文書やリポジトリーの文脈を必要とする曖昧な分類
• Hermesのランタイムと承認済みの能力ポリシーの下でツールを使う多段階の調査
• 永続的なメモリやスキルを使うべき文章作成
• エージェントがすでに到達できる非公開コーパスの調査

引き継がない処理

• Switchノードで表現できる単純なif／thenルーティング
• まず低コストの分類器に通すべき大量生成ループ
• n8nから転送すべきでないシークレット。「便利だから」という理由でHermesへトークンを貼り付けない

仕事全体がエージェント型でチャットから起動されるなら、ゲートウェイUXの方が適している可能性があります。仕事別のOpenClawとHermesの比較を参照してください。Hermesを使わずに最初のn8nエージェントを作る場合は、n8nで初めてのAIエージェントを構築するを参照してください。

構築前に契約を選ぶ

n8nが結果を必要とする場合：
イベント → n8nで検証 + 永続キーを確保
         → HTTP Request（Bearer）→ Hermes :8642/v1/responsesまたは/v1/runs
         → n8nで結果を検証 → 人によるゲート → コネクター

Hermesがイベント結果を配信する場合：
イベント → n8nで検証 + 永続キーを確保
         → HTTP Request（V2 HMAC）→ Hermes :8644/webhooks/<name>
         → Hermesエージェントを実行 → 設定済みのHermes配信先

APIサーバーは既定で127.0.0.1:8642を使い、API_SERVER_KEYを必須とし、OpenAI互換の/v1/chat/completions、/v1/responses、Runs APIを公開します。このキーはターミナルやファイル操作を含むHermesのエージェントツール一式へのアクセスを許可するため、バインド先を非公開に保ち、呼び出し元を厳しく制限してください。

webhookアダプターの既定ポートは8644で、ヘルスチェックはhttp://localhost:8644/health、ルートは/webhooks/<name>以下です。webhook実行は、ルートに設定したdeliver先へ結果を送ります。文書化された配信先には、チャットプラットフォーム、GitHubコメント、メール、Home Assistant、logが含まれます。汎用HTTPコールバック先は定義されていません。

n8nはSaaSコネクターと人によるゲートの永続的な状態を引き続き所有し、Hermesは範囲を限定した推論ステップを担います。

webhookイベント契約：小さく明示的に

n8nの項目ツリー全体を渡さないでください。エージェントが推測せずに扱えるタスクオブジェクトを送ります。

契約の例：

{
  "application_key": "ticket-18422",
  "task": "Classify severity and draft a support reply. Do not send email.",
  "customer": {
    "name": "Example GmbH",
    "plan": "business"
  },
  "message": "VPN drops every morning around 09:00.",
  "constraints": {
    "output": "json",
    "fields": ["severity", "rationale", "draft_reply"],
    "language": "en"
  }
}

ルール：

1. 1つのルートに期待する結果を1つだけ定めるか、結果を明確な列挙値で指定する。
2. 永続的なアプリケーションキーはn8nか業務システムに保持する。本文のフィールドはログの相関に使えるが、Hermesはwebhookの重複排除キーとして扱わない。
3. 同じ引き継ぎの再試行には、安定したX-Request-IDを送る。Hermesはwebhook配信IDを1時間キャッシュし、その時間内の重複した実行または配信をスキップする。
4. 送信、返金、削除など、エージェントが_してはいけない_ことを明示する。
5. 添付全体より抜粋を優先する。大きなデータは別の場所に保存し、Hermesが取得を許可された参照だけを渡す。

ワークフローファミリーごとに専用のHermes webhookルート（support-triage、ops-alertなど）を作り、プロンプト、フィルター、シークレット、スキル、配信設定を個別に定めてください。すべてのペイロードフィールドを信頼できない内容として扱います。ランタイムをサンドボックス化し、プロンプトテンプレートを狭め、不要なツールを削除し、破壊的または外向きの操作には承認を残します。

Hermes V2 HMACの正確な契約

汎用のn8n送信元について、現行のHermesドキュメントはV2を指定しています。

• ヘッダーX-Webhook-Timestamp：Unix秒。
• ヘッダーX-Webhook-Signature-V2：小文字の十六進数で表したHMAC-SHA256。
• 署名対象バイト：<timestamp>.<raw-request-body>。
• リプレイ防止時間枠：タイムスタンプとHermesの時計の差が±300秒以内であること。

本文だけを対象にするV1のX-Webhook-Signature形式にも互換性はありますが、リプレイ防止機能はありません。新しいワークフローでは使わないでください。上流のセキュリティー契約を参照してください。

セルフホストn8nの署名ノード

HERMES_WEBHOOK_SECRETはn8nプロセスのシークレットまたは環境変数の仕組みにだけ保存します。Setノードやコミット対象のワークフローJSONには入れないでください。n8nの設定がモジュールとノードからの環境変数アクセスを許可している場合に限り、CodeノードでNode組み込みのcryptoモジュールを使います。

const { createHmac } = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify($json.hermes_payload);
const secret = $env.HERMES_WEBHOOK_SECRET;

if (!secret) throw new Error('HERMES_WEBHOOK_SECRET is not configured');

const signature = createHmac('sha256', secret)
  .update(`${timestamp}.${body}`, 'utf8')
  .digest('hex');

return [{ json: { body, timestamp, signature } }];

セルフホストのn8nでは、現行のCodeノードのモジュール設定に従い、必要な組み込みモジュールだけを許可してください。任意の外部モジュールを有効にしてはいけません。外部Task Runnersを使う場合は、メインのn8nコンテナーだけでなく、NODE_FUNCTION_ALLOW_BUILTIN=cryptoをenv-overrideとして/etc/n8n-task-runners.jsonに設定します。$envへのアクセスはN8N_BLOCK_ENV_ACCESS_IN_NODEにも左右されます。セキュリティーポリシーで禁止されている場合は、組織が承認した署名サービスか、シークレットストアを使うカスタムノードを利用してください。シークレットをワークフローへ貼り付けてはいけません。

HTTP Requestノードを次のように設定します。

署名後にHTTPノードの構造化JSONエディターを使わないでください。再シリアル化によってバイト列が変わる可能性があります。2xx以外では安全側に倒して失敗させます。200応答は、ルートと配信IDによって配信済みまたは重複を意味し、n8n向けの構造化されたエージェント結果ではありません。Hermesがイベントを受理または配信しただけで、n8nの永続キーをcompletedにしないでください。

LAN内だけのHermes webhookでも、文書化された認証を使ってください。ネットワーク上の近さは認証ではありません。現行の既定値では、各webhookルートを毎分30要求に制限し、1 MBを超える本文を拒否し、X-Request-IDまたはX-GitHub-Deliveryの値を1時間キャッシュします。これらは期限付きの転送制御であり、永続的な業務保証ではありません。

webhook本文には顧客メッセージが含まれることがよくあります。Hermesとn8nは非公開ネットワークか、管理された暗号化オーバーレイに置いてください。内容を承認済みの境界内に保つ必要がある場合は、HermesでローカルのOpenAI互換モデルのベースURLを優先します。n8nからローカルエンドポイントを使うも参照してください。HMACが認証するのは送信元であり、ペイロード内の業務フィールドを書いた人ではありません。

戻り値と送信主体

どのインターフェースを選ぶかによって、結果の受信者が決まります。

A. Hermesが配信を管理するwebhookイベント

ルートがエージェントを実行し、応答を設定済みのHermes配信先へ送ります。n8nが受け取るのはアダプターの状態であり、エージェントの構造化された回答ではありません。Slack、Telegram、GitHub、メール、または文書化された別の配信先が最終目的地で、その後のn8nステップが内容を必要としない場合に使います。

B. n8nへ返すAPI結果

n8nが回答を受け取る必要がある場合は、POST http://127.0.0.1:8642/v1/responsesをAuthorization: Bearer <API_SERVER_KEY>付きで呼び出します。1つの同期HTTP要求を待たせるのではなく、エージェントステップを実行として送信し、監視する場合は/v1/runsを使います。APIは既定でループバックにバインドされますが、そこでもBearerキーは必須です。

{
  "model": "hermes-agent",
  "input": "Classify severity and draft a reply. Return the agreed JSON fields."
}

呼び出し後、n8nは応答スキーマを検証し、永続的なアプリケーションキーへ関連付けて、人によるゲートを開きます。Hermes APIの5分間のIdempotency-Key応答キャッシュは、直後の再試行を安全にしやすくします。n8nの永続的な確保、ユニーク制約、業務状態の遷移を代替するものではありません。

障害モード

Hermesが本当にn8nのインターフェースを調査または操作する必要がある場合だけ、Hermes MCPを使ってください。実際の契約がHTTP API呼び出しかイベントwebhookなら、そちらの方が単純です。

例：サポートフォーム → Hermes API → 人によるゲート

導入済みまたは特定の性能を主張しない、正常経路の例です。

1. Webサイトのフォームからn8n webhookの/support-intakeへPOSTする。
2. n8nがメール、メッセージ長、送信元の列挙値を検証し、ticket-<uuid>を永続的に確保する。
3. ポリシーで必要なフィールドをn8nで削除し、範囲を限定したタスクを構築する。
4. HTTP RequestからHermes /v1/responsesをポート8642で呼び出し、Bearer認証情報と短期間のIdempotency-Keyを使う。
5. Hermesがエージェント結果をn8nへ返す。
6. n8nが必須フィールドを検証し、永続的なチケットキーの下に下書きを保存する。
7. 承認者が保存済みの下書きを承認または拒否する。
8. 承認済みの下書きだけをn8nのメールまたはCRMコネクターへ渡す。

この経路では、送信能力のあるツールをHermesへ渡すべきではありません。プロンプトに「送信しない」と書くことはできますが、信頼できない内容がエージェントを誘導しようとした場合に実効性を持つ制御は、能力の削除とn8nのゲート付きコネクターです。

n8nへ戻す必要のない社内Slack要約には、代わりにwebhookインターフェースを使います。deliver: slackを設定し、イベントへ署名し、安定したX-Request-IDを送信して、アダプター応答は配信状態としてだけ扱います。

署名と時計のずれ

webhook経路では、次を守ります。

• JSONを一度だけシリアル化し、その正確なバイト列へ署名して、同じバイト列を送信する。
• n8nとHermesの時計を同期する。V2署名が正しくても、300秒の時間枠を外れると拒否される。
• 現行の一次ドキュメントは、現在と直前のwebhookシークレットを同時に使う方法を定義していない。導入済みバージョン向けに、管理された切り替えまたは文書化されたローテーション手順を使う。
• 署名失敗をルート名と非機密の相関識別子とともに記録する。シークレットは記録しない。

n8nをDockerで動かし、Hermesをホストで動かす場合は、n8nプロセスのネットワーク名前空間からルーティングできる安定したアドレスを使います。この構成ではlocalhostが別々の名前空間を指します。

カスタムコールバックは別の連携

現行のHermes webhookドキュメントは、汎用HTTPコールバック配信先を挙げていません。導入環境でカスタムコードまたはツールを使って追加する場合は、別の連携として説明し、固定した送信先許可リスト、認証、スキーマ検証、SSRF境界、永続的な冪等性、受け入れテストを個別に設けてください。受信webhook本文のcallbackフィールドが、Hermesの組み込み機能を有効にするかのように説明してはいけません。

判断用の早見表

最小限の構築順序

API結果の経路：

1. ループバックまたは非公開インターフェースでAPIサーバーを有効にし、API_SERVER_KEYを設定する。
2. n8nランタイムのネットワークから、認証済みの/v1/modelsと簡単な/v1/responses呼び出しを1回検証する。
3. 応答スキーマ検証と永続的なn8nアプリケーションキーを追加する。
4. 顧客に影響するコネクターの前に、人によるゲートを追加する。
5. 5分間のAPIキャッシュ内とキャッシュ外の再試行をテストする。

イベントwebhookの経路：

1. webhookアダプターを有効にし、1つのルート、シークレット、範囲の狭いプロンプト、限定的な能力、配信先を設定する。
2. n8nランタイムのネットワークから/healthと、V2署名付きの簡単なイベントを1つ検証する。
3. 安定したX-Request-IDを送り、配信済みと重複のアダプター状態を確認する。
4. 簡単なトリガーを、検証済みの実イベントと永続的なn8nキーに置き換える。
5. レート、本文サイズ、署名、時計、配信、サービス停止の障害をテストする。

本番トラフィック前の受け入れテスト

APIインターフェースについては、次の証拠を保持します。Bearerキーがない、または誤っている要求は拒否される。簡単な要求が期待するスキーマを返す。同じIdempotency-Keyで直ちに再試行しても2回目のエージェント実行を作らない。5分間のキャッシュ後の再試行も永続的なアプリケーションキーで阻止または調整される。Hermesの停止が目に見える待避状態を作る。拒否された下書きが送信コネクターへ到達しない。

webhookインターフェースについては、次の証拠を保持します。署名のない要求、署名後に変更された本文、300秒の時間枠外のタイムスタンプは拒否される。署名付きの簡単なイベントが設定済みの配信先へ届く。同じX-Request-IDを使って1時間以内に繰り返し、2回目のエージェント実行や配信なしで重複状態になる。さらに、レート制限、本文の超過、配信先の停止、Hermesの停止がn8nから確認できる。

該当するインターフェースが受け入れテストに合格し、責任の所在が明確になって初めて、連携を試験導入できます。Bearer認証とHMACは、それぞれ文書化された契約の範囲でのみ呼び出し元のIDを確立します。5分間のAPIキャッシュと1時間のwebhook配信IDキャッシュは、期限付きの再試行補助です。永続的なアプリケーション冪等性、認可、承認状態、業務復旧は、引き続きn8nまたは業務システムが担います。