Skip to content
← Back to release · 2.1.317
New features / v2.1.317

Add onFailure block for SDK hooks

CHANGELOG · original

Added onFailure: "block" for Agent SDK hook callbacks, so a callback that fails blocks the action instead of letting it run
Open official changelog ↗

Documentation

Documentation excerpt

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, such as a team's shared audit service. The configuration below posts every successful tool call 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"]
          }
        ]
      }
    ]
  }
}

Your endpoint responds with a JSON body in the same output format as command hooks, and Claude Code also checks the response status:

  • 2xx status: to block a tool call, return the appropriate hookSpecificOutput fields in the body.
  • Any other status, or the request fails: Claude Code reports a non-blocking error and lets the action continue, unless the hook is one whose failure blocks the action. To make a failed endpoint block the action, set onFailure: "block" on the hook.

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.

Documentation snapshot · 2026-11-20

Change details