Claude Code: HTTP Hooks for Web-Native Event Integration

HTTP Hooks: A New Transport for Claude Code's Event Lifecycle

Claude Code v2.1.63 introduces HTTP hooks, a second hook transport alongside the existing shell-command hooks. Where shell hooks execute a local process and read its stdout, HTTP hooks POST the same lifecycle event payload as JSON to any URL and expect a structured JSON response. This means any HTTP server — a serverless function, a webhook proxy, or a simple Express route — can participate in Claude Code's event lifecycle without shell scripting.

The hook configuration accepts a new type: "http" field alongside a url property. When an event fires, Claude Code serializes the event payload (session ID, event type, tool name, input arguments, and any file paths involved) into a JSON body and sends it as a POST request to the configured URL. The server has a configurable timeout window (default five seconds) to respond.

Response Protocol and Decision Model

The HTTP response protocol mirrors the shell hook contract: the server returns a JSON object with a decision field set to "allow", "deny", or "modify". An allow decision lets the action proceed unchanged. A deny decision blocks the action and surfaces an optional reason string to the user. A modify decision replaces the original action parameters with the values in an updatedInput field, enabling the server to rewrite tool inputs before execution.

If the server returns a non-2xx status code, times out, or returns malformed JSON, Claude Code treats the hook as failed. Failed hooks default to the allow behavior — the action proceeds — unless the hook configuration includes "failOpen": false, in which case a failure blocks the action. This fail-open default keeps the developer experience smooth during transient network issues.

Use Cases and Limitations

HTTP hooks open several integration patterns that were awkward with shell hooks. A centralized compliance server can review every file-write event across a team and enforce organization-wide policies without distributing shell scripts to every developer machine. A Slack or Discord bot can receive notification events and post summaries in real time. A mobile approval system can hold a pending action until a developer taps "approve" on their phone.

The current limitations are worth noting: HTTP hooks do not support streaming responses, so they cannot provide progress updates during long-running decisions. Authentication is the caller's responsibility — Claude Code sends the payload as-is, so the URL must include any necessary tokens or the server must validate requests by other means (IP allowlisting, shared secrets in headers, etc.). The timeout ceiling is 30 seconds; hooks that need longer processing should respond immediately with allow and handle the logic asynchronously.

MCP OAuth Manual URL Paste Fallback

The same release addresses a persistent pain point with MCP server authentication. When Claude Code initiates an OAuth flow for an MCP server, it opens the authorization URL in the system browser. In containerized, remote, or headless environments, this browser launch often fails silently, leaving the user stuck. v2.1.63 adds a manual fallback: if the browser does not open within a few seconds, Claude Code prints the full authorization URL to the terminal and prompts the user to paste the callback URL after completing authentication in any browser. This simple change unblocks MCP OAuth in Docker containers, SSH sessions, and CI environments where browser automation is unavailable.