HTTP hooks

Use type: "http" hooks to POST event data to an HTTP endpoint instead of running a shell command. The endpoint receives the same JSON that a command hook would receive on stdin, and returns results through the HTTP response body using the same JSON format.

HTTP hooks are useful when you want a web server, cloud function, or external service to handle hook logic: for example, a shared audit service that logs tool use events across a team.

This example posts every tool use to a local logging service:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

The endpoint should return a JSON response body using the same output format as command hooks. To block a tool call, return a 2xx response with the appropriate hookSpecificOutput fields. HTTP status codes alone can't block actions.

Header values support environment variable interpolation using $VAR_NAME or ${VAR_NAME\} syntax. Only variables listed in the allowedEnvVars array are resolved; all other $VAR references remain empty.

For full configuration options and response handling, see HTTP hooks in the reference.