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
hookSpecificOutputfields 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