In short: Setting up Inference hooks is two jobs. An Owner turns the feature on in claude.ai under Organization settings › Data and privacy, saves an HTTPS address, and sets the timeout, failure handling, and rollout. In parallel, somebody builds the AI security server that answers every signed POST with {"action": "allow"} or {"action": "deny"}. It has to be HTTP 200, or the response counts as a failure rather than a denial. With the Validate tool calls switch on, the same server also sees every tool call Claude makes, before it runs.
What you need first
| Requirement | Where it stands |
|---|---|
| Plan | Claude Enterprise. Platform organizations, meaning API access through the Claude Platform, are out of scope. The feature does not exist on Amazon Bedrock or Google Cloud. |
| Role | The organization:manage permission, held only by Owner and Primary owner. The Admin role does not have it. |
| Endpoint | An https:// URL on port 443, on a publicly routable host, reachable without redirects, with a certificate that validates against the public CA trust store. The host needs an IPv4 address, which Anthropic uses even when the host also has IPv6 addresses; localhost or an IPv6 address as the host is refused. |
| Maturity | Beta. Field names, request shapes, and headers may still change. |
Private, loopback, and carrier-grade NAT addresses are refused at connect time. Reverse tunnels such as ngrok are blocked by Anthropic’s network policy, so don’t test through a tunnel. Host the server on a domain you control.
The three states
The settings read more easily as three states than as a pile of switches:
| State | What is set | What happens |
|---|---|---|
| Off | Enforce verdicts off | Your server is never contacted, nothing is inspected |
| Shadow | Enforce verdicts on, Mode set to Shadow mode | Your server receives prompts and answers, nothing is blocked |
| Enforcing | Enforce verdicts on, Mode set to Allow the request or Block the request | A deny blocks the request |
Setting it up, step by step
1. Allow the feature
claude.ai › Organization settings › Data and privacy › the Inference hooks section › turn on Allow for your organization.
This only unlocks the settings page. It always forces Enforce verdicts off, even for a configuration that was enforcing before, so allowing the feature never starts inspection by itself.
2. Open the settings page
The page sits under Data and privacy and has no entry of its own in the settings nav; its breadcrumb reads Data and privacy / Inference hooks. Until you save an endpoint, the page warns that nothing is being inspected, and Enforce verdicts carries a Requires endpoint badge.
3. Save the endpoint
Configure opens the Set up endpoint dialog. It asks for the Endpoint URL and accepts only https://. Nothing else at this point. Next saves it, and the button then reads Edit.
The whole URL you enter is the endpoint. There is no fixed path suffix, so pick any path that suits your server.
4. Lock away the signing secret
The first save generates the webhook signing secret and reveals it once. Copy it and store it securely before you click Next. It cannot be retrieved later, only rotated.
5. Add headers and test the connection
Next on the secret dialog reopens the endpoint dialog with two more controls.
Custom request headers: up to 16 static headers sent with every request so your server can authenticate the caller. Values are stored encrypted and never shown again; only the names stay visible. Because they are write-only, every change means re-entering all of them. Changing the URL clears every stored value so your credentials never reach a new destination, so re-enter them after a URL change.
Header names use standard HTTP token characters with - rather than _. Reserved and therefore rejected: framing headers such as Content-* and Host, proxy and cookie headers, client-address headers such as X-Forwarded-*, the webhook-* signature headers, and anything prefixed X-Anthropic-. Values must be printable ASCII.
Test connection sends a synthetic test prompt to the URL and headers currently in the form, not to the saved ones, so re-enter stored header values before testing. The result says whether your server answered allow or deny, which catches a deny-everything default before you start enforcing. It also shows the round-trip time Anthropic measured for that one test request, on a fresh connection and including the handshake.
| Failure result | What to check |
|---|---|
| URL rejected | The URL failed a structural check. Use https:// on port 443. |
| Private or internal IP | The host is a private or internal IP address, an IPv6 address, or localhost. A hostname that resolves to such an address shows up as a transport error instead. |
| Timeout | No verdict within the timeout. |
| Transport error | DNS, the TLS handshake, or the connection failed. |
| Non-200 status | Anything other than HTTP 200. Redirects are not followed and count as failures. |
| Unparseable response | A response arrived, but it is not a valid verdict. |
| Signing secret required | No secret exists, so the test would go out unsigned. Click Generate secret under Request signing. |
6. Failure handling and timeout
Under Failure handling, Mode decides what applies while your server is unreachable or too slow:
- Block the request: inference stops when no verdict arrives (fail closed).
- Allow the request: the request reaches the model uninspected (fail open).
The third option in the same dropdown, Shadow mode, is a rollout tool, not a failure policy.
Prompt verdict timeout (ms) ranges from 1 to 10,000, defaulting to 5,000. The budget covers the whole exchange: connection, TLS handshake, request, and response. A slow verdict counts as an unreachable server, so use the lowest value your server reliably meets.
Changes in this section save as you type them. On first save the defaults are Allow the request and 5,000ms.
7. Rollout percentage
Under Rollout, Requests inspected (%) runs from 0 to 100 and decides what share gets inspected. The roll happens once per conversation turn, so a single conversation can be inspected on some turns and not others. Anything outside the sample proceeds uninspected, even with failure handling set to Block the request.
8. Start enforcing
Turn on Enforce verdicts and confirm in the dialog, which restates your failure handling choice. Allow about a minute for the change to reach every Anthropic server; requests already in flight finish under the old setting. Turning it off works just as quickly and keeps your configuration.
Directly below Enforce verdicts sits Validate tool calls. The switch also sends the tool calls in each of Claude’s responses to your server and waits for its verdict before they run. A new configuration has it on. It does nothing while Enforce verdicts is off, and a change to it takes about a minute to reach every Anthropic server, as with Enforce verdicts.
To watch before you block: set Mode to Shadow mode in step 6 first, then turn on Enforce verdicts. Your server receives real prompts and answers exactly as it would when enforcing, and nothing is blocked, not a deny and not an outage, with the end user seeing nothing. The settings page then shows a Shadow mode — not blocking badge. With Validate tool calls on, tool call frames arrive too, and no tool call is blocked. To leave, set Mode back to Allow the request or Block the request.
The server: the smallest thing that works
The smallest useful server reads the request and lets it through. This example is the one in the docs:
# Run with: python server.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class VerdictHandler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1" # keep the connection open between verdicts
def do_POST(self):
# Drain the body; transcripts can be megabytes.
self.rfile.read(int(self.headers.get("Content-Length", 0)))
verdict = b'{"action": "allow"}'
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(verdict)))
self.end_headers()
self.wfile.write(verdict)
ThreadingHTTPServer(("", 8000), VerdictHandler).serve_forever()
It accepts everything, unsigned requests included. Signature verification goes in before you start enforcing.
What arrives
Every request carries these fixed headers, plus your own and the webhook-* signature headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | anthropic-dlp/1 |
Accept-Encoding | identity |
The body is a JSON object. There are two events, told apart by the top-level type field. The prompt frame arrives once per governed inference request, before inference begins. The tool call frame arrives when a response contains tool calls and Validate tool calls is on, before the first of them runs. Either way, Anthropic waits until your server answers or the timeout elapses.
The prompt frame looks like this:
{
"type": "prompt",
"request_id": "req_abc123",
"tenant_id": "11111111-1111-1111-1111-111111111111",
"actor": {
"type": "user",
"id": "user_01AbCdEfGhIjKlMnOpQrStUv",
"email_address": "alice@example.com"
},
"source": { "application": "claude-ai" },
"session_id": "22222222-2222-2222-2222-222222222222",
"model": "claude-sonnet-4-5",
"messages": [],
"metadata": {}
}
request_id is the same value as the webhook-id header. source.application is an open string, not a closed enum: common values are claude-ai, claude-code, and cowork, while connection tests and the circuit breaker’s recovery checks arrive as config-test. Treat the field as routing metadata, not as a trust boundary.
messages holds the transcript as the user sees it: text, tool calls and their results, extracted attachment text, earlier turns. There are four block types, text, tool_use, tool_result, and attachment. A tool_result block carries tool_name and tool_use_id alongside content and is_error, so a policy doesn’t have to hunt for the matching tool_use block. What never appears: system prompts, tool definitions, Anthropic-internal context, Claude’s hidden reasoning, and raw file bytes.
Two things trip people up in practice:
- A turn whose blocks are all excluded is dropped entirely. Don’t assume user and assistant alternate cleanly.
- Transcripts arrive untruncated. In practice the context window keeps bodies under about 10 MB; the protocol allows 64 MiB. Common defaults sit far below that: nginx
client_max_body_sizeis 1 MB,express.json()is 100 kB. A rejected body is a webhook failure, and with failure handling on Allow the request, the oversized prompt then reaches the model uninspected.
The tool call frame
When Claude produces tool calls, Anthropic sends one frame listing them. A single verdict covers the whole frame: you can’t allow some calls and deny others. The frame goes to the same endpoint, with the same headers, the same signature, and the same top-level fields. Calls made by code running in the code execution tool arrive the same way, in separate frames, before they run.
Three differences from the prompt frame:
typeis"tool_call".messagesholds only the latest message, the assistant message Claude just produced: anytextblocks and onetool_useblock per call, in the order the model produced them. Earlier turns are left out, because the prompt frame before it carried them. Read the last entry ofmessages, because the protocol may later add earlier messages before it.- Each
tool_useblock carries atool_infoobject.
Where session_id is set, it is the same on both frames; request_id is the frame’s own, and as opaque as the prompt frame’s.
tool_info says who runs or provides the tool, not what the tool can reach. There are four kinds, told apart by the type field, and Anthropic sends the first one that fits:
type | What it is | Own fields |
|---|---|---|
platform | The Claude API runs the tool itself, such as web search or code execution | tool_type with the versioned identifier such as web_search_20250305, plus optional toolset_name |
application | The calling Anthropic application provides it, such as claude.ai’s own tools | optional toolset_name |
third_party | A server Anthropic knows of: a claude.ai connector or an MCP server named in mcp_servers | optional toolset_name and origin, plus verified_origin wherever origin is set |
client | Any other tool, usually one the calling application runs, bash and computer use included | optional tool_type and toolset_name |
Four things that are no use as a trust boundary. tool_name is chosen by whoever defined the tool, and a server’s toolset_name by whoever wrote the request or named the connector. A name copied from tool_name is not the one the user sees: mcp__Google_Drive__search_files gives Google_Drive, and with two connectors of the same name a short suffix is appended (Gmail-1a2b3c4d). origin may be a private or local address, localhost included, and an absent origin means unknown, not safe. verified_origin is true only when Anthropic’s servers connect to the tool server themselves; for a claude.ai connector it can be false regardless. A type you don’t recognize is accepted; rely only on type for such a kind.
A tool on an MCP server that Claude Code reaches directly from the user’s machine is a client tool with {"type": "client"}. A deny stops the call before Claude Code runs it. The exchange between Claude Code and a local server doesn’t pass through Anthropic, so you see the result only when Claude Code sends it back: as a tool_result block in the next prompt frame.
What goes back
HTTP 200 and a JSON verdict, for both outcomes. To allow:
{ "action": "allow" }
To deny:
{
"action": "deny",
"deny_reason": "This prompt appears to contain customer payment card data, which your organization's policy does not allow.",
"reference_id": "scan_01HXPT4R9V"
}
| Field | Constraints | Meaning |
|---|---|---|
action | allow or deny, required | Any other value is a webhook failure, not a denial. |
deny_reason | String or null, at most 500 characters | What the user sees. Longer values are truncated. Ignored on allow. |
reference_id | String or null, at most 50 characters from [A-Za-z0-9._:/-] | Your own identifier for this evaluation. It lands on the inference_hooks_request_denied activity and is never shown to the user. No content, no personal data. |
A deny is never lost over a formatting problem: an oversize deny_reason is truncated, a malformed reference_id is silently dropped, and the denial still stands. The reverse does not hold. Never signal a denial with an error status. Anything other than HTTP 200 with a parseable verdict is a webhook failure, and then your failure handling applies instead of your judgment.
Anthropic reads at most 64 KiB of your response, uncompressed. Redirects are not followed, cookies are ignored, and unknown fields in the verdict are skipped.
A tool call frame takes the same verdict body, field for field. An allow lets the calls run and the response continue; a deny stops all of them and ends the response with the same error as a denied prompt, including your deny_reason. Text delivered before the first call is not taken back.
Verifying the signature
Requests are signed per the Standard Webhooks specification, using three headers. Anthropic sends the names in lowercase and proxies are free to re-case them, so look them up case-insensitively.
| Header | Contents |
|---|---|
webhook-id | Unique identifier for this delivery, identical to request_id in the body. Works as an idempotency key and is the first component of the signed payload. |
webhook-timestamp | Unix time in seconds as a decimal string. Reject anything more than five minutes from your clock, in either direction. |
webhook-signature | One or more space-separated v1,<base64> values, each an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body bytes}. Accept if any one matches, using a constant-time comparison. |
Two mistakes account for most verification bugs:
- Compute over the raw bytes, the body exactly as it arrived, before any parsing or re-encoding.
- Decode the secret with a standard base64 decoder. The key is the part after the
whsec_prefix, in the standard alphabet with+and/. A URL-safe decoder derives the wrong key bytes whenever the secret contains+or/, which is most of the time.
The check in Python, as the docs give it:
import base64, hashlib, hmac, time
TOLERANCE_SECONDS = 300
def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
lowercased = {name.lower(): value for name, value in headers.items()}
try:
message_id = lowercased["webhook-id"]
timestamp = lowercased["webhook-timestamp"]
signatures = lowercased["webhook-signature"]
except KeyError:
return False # unsigned: not from Anthropic
try:
signed_at = int(timestamp)
except ValueError:
return False
if abs(time.time() - signed_at) > TOLERANCE_SECONDS:
return False # replayed, or the clocks disagree
try:
key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
except ValueError:
return False
payload = f"{message_id}.{timestamp}.".encode() + body
expected = b"v1," + base64.b64encode(
hmac.new(key, payload, hashlib.sha256).digest()
)
return any(
hmac.compare_digest(expected, candidate.encode())
for candidate in signatures.split()
)
Once your organization has a secret, every request is signed, the connection test included, because the setup flow generates the secret before the first test. So reject unsigned requests. One exception: organizations that turned Inference hooks on before the secret was required keep sending unsigned requests until an administrator generates one.
Rotation is an immediate cutover with no overlap. Requests signed with the old secret still arrive for about a minute afterwards, plus whatever was already in flight, so let your server accept both signatures during the switchover.
Running it
- Retry: exactly once, after 100ms, and only when the connection attempt itself fails. The retry shares the same timeout budget and carries the same
webhook-idand signature. Once your server has answered, the exchange is never retried. - Deduplication: on
webhook-id. If you record verdicts, key the records on it. - Circuit breaker: sustained failures attributable to your server trip it. Anthropic then stops contacting your server, and your failure handling applies to every request. Under Block the request, that means your people are blocked until it resets. Starting 10 minutes after the trip, Anthropic checks at most about once a minute with the same synthetic test request; a valid verdict, allow or deny, resets it. Change any setting after a trip, even just rotating the secret, and those checks stop. Then you turn Enforce verdicts back on by hand. Administrators are also notified of a trip in the claude.ai notification center. Turn Enforce verdicts off yourself and automatic recovery doesn’t apply at all; it covers trips only.
- One breaker for both frames: prompt frames and tool call frames share it, and failures on either count toward it. In shadow mode no failure counts toward it.
- Source IPs: requests come from
160.79.106.0/24, part of Anthropic’s published outbound ranges. The inbound ranges on the same page don’t cover it. An allowlist narrows your exposure but does not replace signature verification, since other Anthropic egress traffic uses the same block. - Latency: your server’s round trip sits on every governed request in the organization. With Validate tool calls on, a response that produces tool calls waits for its verdict too, in shadow mode as well. Load-test it before rolling out to a large one.
Staying forward compatible
The protocol grows. Your server has to skip unknown top-level fields on either frame, unknown keys in metadata, new source.application values, new actor.type values, blocks with an unrecognized type, and messages with a role other than user or assistant, rather than rejecting the request.
One special case: more event types are announced. If the top-level type is one you don’t recognize, skipping won’t do, because the request still needs a verdict. Return allow, not an error status. An error is a webhook failure, and sustained webhook failures trip the circuit breaker.
What the user sees on a deny
The message has two parts: your server’s deny_reason, then a blank line, then a standing text administrators set under Custom blocked prompt message, up to 500 characters, usually who to contact or where to request an exception. With no custom text, a built-in default points at the administrators; the appended part can also be switched off entirely, leaving only the deny_reason.
So write the deny_reason for the user rather than for your own team: what to change, which kind of content has to go, and not a scanner code only you can read.
Every denial is also recorded in the organization’s Activity Feed. A blocked message stays in the conversation on claude.ai, and the Inference hooks system keeps no copy of prompts or responses of its own, only configuration and metadata such as verdicts, timestamps, and request identifiers.
Who gets inspected
The whole Who is inspected section sits behind one switch, Limit by role. With it off, every governed request is inspected. Turn it on and Inspect starts on Everyone except excluded roles, with the roles you pick below it: their members are never covered, and their prompts never reach your server. Only custom roles your organization created are offered, not the built-in ones, and the list starts empty. The exemption covers a person’s interactive sessions. Changing the list requires identity management permission, and the change is recorded in the Activity Feed as rbac_role_permission_added or rbac_role_permission_removed.
It works the other way round too. To try Inference hooks on part of the organization, set Inspect to Only selected roles and pick the roles in the dialog. From then on, only members who are set to Custom roles and hold a selected role are inspected. Anyone set to another role, such as User or Owner, is not inspected even while holding a selected role, and that includes you as Owner or Primary owner. Remove every excluded role before you switch: an organization uses exclusions or selected roles, not both.
Three things that apply while it is set:
- A custom role with All capabilities or All generally available counts only if you select it, like any other role.
- If no member set to Custom roles holds a selected role, nobody is inspected.
- Requests with no member behind them aren’t inspected, such as requests made with API keys and Claude Tag conversations in Slack.
To go back to inspecting everyone, turn Limit by role off: after you confirm, every excluded role is removed and Only selected roles is off.
Keeping an eye on it
The endpoint health area of the settings page shows status (Healthy, Tripped, Not enforcing, Not configured), failures per minute averaged over the last two minutes, the block rate while the rollout percentage is below 100, and when the circuit breaker last tripped. Recent errors lists the ten most recent failures with the time, an error type, and a category: webhook_error for a problem at your endpoint or the connection to it, relay_error for a failure inside Anthropic’s systems. A DlpWebhookStatusError entry also carries the HTTP status your server returned and the size of the body Anthropic sent, such as HTTP 413 · 1.3 MB. Content and your endpoint URL never appear, and the list clears an hour after the last failure.
Which error type counts toward the circuit breaker is the part of the table you need when it matters:
| Error type | What happened | Counts toward the breaker |
|---|---|---|
DlpWebhookTimeoutError | No verdict within your timeout | yes |
DlpWebhookStatusError | A status other than 200, redirects included | yes |
DlpWebhookResponseError | Status 200, but not a valid verdict, or larger than 64 KiB | yes |
DlpWebhookDisallowedAddressError | The host is private, internal, IPv6, or localhost | yes |
DlpWebhookTransportError | The connection failed or dropped, DNS, TLS, or a hostname that resolves to a private address | no |
DlpWebhookBlockedError | The URL isn’t https:// on port 443 or can’t be parsed, so no request went out | no |
DlpWebhookRelayError | The failure was inside Anthropic’s systems, and your server usually wasn’t contacted | no |
The docs name two limits themselves. The panel is best-effort and shows zero failures when it cannot read the counters, so a healthy-looking panel is no proof of a healthy server. And failures per minute counts network and DNS errors that never trip the breaker, so the number can run high while Circuit breaker tripped stays empty.
For alerting, the Activity Feed is the better source: each trip is recorded as inference_hooks_circuit_breaker_tripped, one activity per trip rather than one per affected request. That requires the Compliance API to be enabled for the organization. While the breaker is tripped, no per-request activities are written, so the trip activity is the only record of that window. Automatic recovery is never recorded, in any mode.
The feed also carries the requests that proceeded without a verdict, though only while Enforce verdicts is on and Mode is Allow the request. The reason reads endpoint_timeout, endpoint_error for any other problem calling your server, or internal_error for a failure on Anthropic’s side. Under Block the request and in shadow mode, no such individual record is written.
Turning it off again
Two levels:
- Enforce verdicts off on the settings page. Within about a minute, prompts stop going to your server, and requests already in flight finish under the old setting. The page stays available, which makes this the pause to use while you work on the server.
- Allow for your organization off in Data and privacy settings. The settings page goes away too. Either way, your endpoint, headers, and secret are kept; turning it back on forces Enforce verdicts off and clears a tripped circuit breaker.
Limits
- Allow or deny only. Rewriting or redacting a prompt is not supported: it goes through whole or not at all.
- Two events, and the second one has gaps.
promptfires once per governed inference request.tool_callfires on tool calls in a response, but only with Validate tool calls on, and it may leave out calls to some of claude.ai’s own tools: listing, searching for or suggesting connectors, plugins or skills; suggesting research or web search; searching for other tools; switching to a larger model; ending the chat; giving Claude the user’s local time; reading the user’s own past chats and saved memory. Those calls and their results stay in the conversation, so the next prompt frame from it includes them, if there is one. - Attachments arrive as metadata and extracted text. Raw file and image bytes are never sent, so image-only content, a screenshot of a document for instance, is not inspected.
- Voice mode is covered only partly. Prompts and tool calls do reach your endpoint, but a small share of the calls doesn’t, so it is no use as your only control for voice. Deny there and the call usually ends with a general error message, with your
deny_reasonnot shown. - Not covered: system prompts and tool definitions. Plus the model calls Anthropic makes for the organization itself: Claude Security’s hosted scans, Code Review’s reviews on GitHub pull requests, and the building of smart reports. What a user starts themselves is governed, so a session opened to fix a security finding, the Claude Security plugin in Claude Code, a local
/code-review, and whatever they type or upload when creating a report. - Not available: to Platform organizations, on Amazon Bedrock, or on Google Cloud.
- Beta. Field names, request shapes, and headers may change. This guide gets checked against the docs on the next run.
If you would rather look afterwards than intervene beforehand, that is what the Compliance API is for. Inference hooks acts inline and decides in real time, with Anthropic calling your server. The Compliance API works after the fact, and you call Anthropic.
Changes
- 2026-11-10: Checked against the docs and brought up to date, six deviations. There is a second event,
tool_call, plus the Validate tool calls switch, which is on in new configurations; the guide said response-side enforcement did not exist yet. New section on the tool call frame andtool_info. The exclusions section is now Who is inspected, sits behind Limit by role, and can also narrow inspection to selected roles. Voice mode is inspected; the guide listed it under “not covered”. What is not covered instead: the model calls Anthropic makes for the organization itself. Recent errors now names a category and an error type, and which of them trips the circuit breaker. Smaller items: the IPv4 requirement for the host, the round-trip time in the connection test,tool_nameandtool_use_idon thetool_resultblock, the administrator notification on a trip, and the reasons recorded for requests that proceeded uninspected. - 2026-09-22: First version. Every statement checked against the docs as of 2026-09-22.
Sources
- Inference hooks (platform.claude.com)
- Configure Inference hooks (platform.claude.com)
- Develop an Inference hooks integration (platform.claude.com)
- Inference hooks overview (support.claude.com)