Claude Code ガイド

Appearance

HTTP Hooks：URLへのJSON POSTでフックを設定できる新機能 ​

原文（日本語に翻訳） ​

HTTPフックが追加されました。シェルコマンドを実行する代わりに、URLにJSONをPOSTしてJSONレスポンスを受け取ることができます。

原文（英語） ​

Added HTTP hooks, which can POST JSON to a URL and receive JSON instead of running a shell command

概要 ​

Claude Code v2.1.63から、フック設定にHTTPフックが追加されました。command・prompt・agent に並ぶ4つ目のフックハンドラータイプとして、指定したURLにフックイベントのJSONデータをPOSTし、レスポンスのJSONで動作を制御できるようになりました。外部サービス・Webhookエンドポイント・マイクロサービスとのシームレスな連携が可能になり、組織全体のポリシー適用や監査ログの外部送信などに活用できます。

基本的な使い方 ​

settings.json でのHTTPフック設定 ​

.claude/settings.json または ~/.claude/settings.json を直接編集して設定します（/hooks メニューからは設定できません）：

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTPフック固有のフィールド ​

フィールド必須説明
type必須"http" を指定
url必須POSTリクエスト先のURL
headers任意追加HTTPヘッダー。$VAR_NAME 形式で環境変数を参照可能
allowedEnvVars任意ヘッダー値で使用できる環境変数名リスト（セキュリティのため必須）
timeout任意タイムアウト秒数
statusMessage任意実行中に表示するスピナーメッセージ

Claude Codeがエンドポイントに送信するJSONの例 ​

json
{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

実践例 ​

外部ログサービスへのツール使用ログ送信 ​

json
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://logging.example.com/claude-tool-usage",
            "headers": {
              "Authorization": "Bearer $LOG_API_KEY"
            },
            "allowedEnvVars": ["LOG_API_KEY"]
          }
        ]
      }
    ]
  }
}

セキュリティポリシーの適用（ツール呼び出しのブロック） ​

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/security-check"
          }
        ]
      }
    ]
  }
}

セキュリティチェックエンドポイントのレスポンス例：

json
// ブロックする場合（2xx + JSON必須）
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "このコマンドはポリシー違反のため実行できません"
  }
}

組織全体のポリシー一元管理 ​

json
{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://policy.company.internal/claude-check",
            "headers": {
              "X-Employee-ID": "$EMPLOYEE_ID"
            },
            "allowedEnvVars": ["EMPLOYEE_ID"]
          }
        ]
      }
    ]
  }
}

一つのHTTPエンドポイントで複数のClaude Codeインスタンスからのリクエストを評価し、組織全体のポリシーを一元管理できます。

Claudeの処理を停止させる ​

エンドポイントが以下のJSONを返すと、Claudeの処理全体を停止できます：

json
{
  "continue": false,
  "stopReason": "ビルドが失敗しました。エラーを修正してから続行してください"
}

注意点 ​

  • 設定ファイルの直接編集が必要：HTTPフックは /hooks インタラクティブメニューから追加できません
  • ブロックにはJSONレスポンスが必要：ツール呼び出しをブロックするには、2xxレスポンスにJSONボディを含める必要があります。非2xxや接続エラーは非ブロッキングエラーとして扱われ、処理が続行されます
  • 環境変数のセキュリティ：ヘッダーで環境変数を使用する場合、allowedEnvVars に列挙されたもののみが解決されます（未列挙の変数は空文字に置換）
  • 並列実行：同じイベントに複数のHTTPフックがある場合、URLが異なれば並列実行されます。同一URLは重複排除されます

関連情報 ​