inference-hooks-configuration changedmanage-claude/inference-hooks-configuration
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+22added
Lines−22removed
From line
14
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits17to this page, all time
The whole hunk
from line 14, old and new numbered
/
from line 14
1414
1515You need:
1616
17* The `organization:manage` permission in claude.ai, which only the **Owner** and **Primary owner** roles hold. The **Admin** role doesn't have it.
18* An AI security server HTTPS endpoint that accepts verdict requests: an `https://` URL on port 443, on a publicly routable host, reachable without redirects. Reverse-tunnel hosts (ngrok and similar tunnel services) are not supported: Anthropic's network policy blocks them. Don't test through a tunnel; host your server on a domain you control. For the full [hosting requirements](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint#receive-a-request), and to build the server and verify signed requests, see [Develop an Inference hooks integration](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint).
17* The `organization:manage` permission in claude.ai, which only the **Owner** and **Primary owner** roles hold. The **Admin** role doesn’t have it.
18* An AI security server HTTPS endpoint that accepts verdict requests: an `https://` URL on port 443, on a publicly routable host, reachable without redirects. Reverse-tunnel hosts (ngrok and similar tunnel services) are not supported: Anthropic’s network policy blocks them. Don’t test through a tunnel; host your server on a domain you control. For the full [hosting requirements](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint#receive-a-request), and to build the server and verify signed requests, see [Develop an Inference hooks integration](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint).
1919
2020## Set up Inference hooks
2121
from line 35
3535 </Step>
3636
3737 <Step title="Open the Inference hooks settings page">
38 Still in **Data and privacy**, open the **Inference hooks** section to reach the Inference hooks settings page. It lives under **Data and privacy** rather than as its own entry in the settings nav, so its breadcrumb reads **Data and privacy / Inference hooks**. Until you save an endpoint, the page warns that prompts aren't being inspected yet, and **Enforce verdicts** stays off with a **Requires endpoint** badge.
38 Still in **Data and privacy**, open the **Inference hooks** section to reach the Inference hooks settings page. It lives under **Data and privacy** rather than as its own entry in the settings nav, so its breadcrumb reads **Data and privacy / Inference hooks**. Until you save an endpoint, the page warns that prompts aren’t being inspected yet, and **Enforce verdicts** stays off with a **Requires endpoint** badge.
3939 </Step>
4040
4141 <Step title="Configure your endpoint">
from line 63
6363 | Result | What to check |
6464 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
6565 | URL rejected | The URL failed a structural check. Use an `https://` URL on port 443. |
66 | Private or internal IP | The URL's host is a private or internal IP address, an IPv6 address, or `localhost`. Use a publicly routable host. |
66 | Private or internal IP | The URL’s host is a private or internal IP address, an IPv6 address, or `localhost`. Use a publicly routable host. |
6767 | Timeout | The AI security server did not return a verdict within the timeout. |
6868 | Transport error | DNS resolution, the TLS handshake, or the connection failed, or the hostname resolves to a private address. |
6969 | Non-200 status | The AI security server responded with a status other than 200. Verdicts must come back as HTTP 200; redirects are not followed and count as failures. |
from line 74
7474 <Step title="Choose failure handling and timeout">
7575 Under **Failure handling**, set **Mode** to choose what occurs while the AI security server is unreachable or verdicts time out:
7676
77 * **Block the request:** stop inference when your AI security server can't deliver a verdict (fail closed).
77 * **Block the request:** stop inference when your AI security server can’t deliver a verdict (fail closed).
7878 * **Allow the request:** let the request proceed to the model without inspection (fail open).
7979
80 The dropdown menu's third option, **Shadow mode**, is a rollout tool rather than a failure policy; see [Shadow mode](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration#shadow-mode).
80 The dropdown menu’s third option, **Shadow mode**, is a rollout tool rather than a failure policy; see [Shadow mode](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration#shadow-mode).
8181
8282 Then set **Prompt verdict timeout (ms)**: 1 to 10,000ms, with a default of 5,000ms. The budget covers the entire exchange, and a slower verdict counts as an unreachable server, so set the lowest value your server can reliably meet.
8383
from line 93
9393 <Step title="Turn on Enforce verdicts">
9494 To evaluate verdicts against live traffic without blocking anyone at first, set **Mode** to **Shadow mode** (step 6) before turning on enforcement; see [Shadow mode](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration#shadow-mode).
9595
96 Turn on **Enforce verdicts** to gate Claude on your AI security server's verdict for every governed prompt, then confirm in the dialog box, which restates your failure handling choice. Allow about a minute for the change to reach every Anthropic server; requests already in flight complete under the old setting. Turning it off stops prompts from being sent to your AI security server, again within about a minute; your configuration is kept.
96 Turn on **Enforce verdicts** to gate Claude on your AI security server’s verdict for every governed prompt, then confirm in the dialog box, which restates your failure handling choice. Allow about a minute for the change to reach every Anthropic server; requests already in flight complete under the old setting. Turning it off stops prompts from being sent to your AI security server, again within about a minute; your configuration is kept.
9797
98 **Validate tool calls**, below **Enforce verdicts**, also sends the tool calls in each of Claude's responses to your AI security server and waits for its verdict before they run; see [The tool call frame](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint#the-tool-call-frame). It is on by default in a new configuration. It has no effect while **Enforce verdicts** is off, and a change to it takes about a minute to reach every Anthropic server, as with **Enforce verdicts**.
98 **Validate tool calls**, below **Enforce verdicts**, also sends the tool calls in each of Claude’s responses to your AI security server and waits for its verdict before they run; see [The tool call frame](https://platform.claude.com/docs/en/manage-claude/inference-hooks-endpoint#the-tool-call-frame). It is on by default in a new configuration. It has no effect while **Enforce verdicts** is off, and a change to it takes about a minute to reach every Anthropic server, as with **Enforce verdicts**.
9999 </Step>
100100</Steps>
101101
102102## Shadow mode
103103
104Shadow mode runs your hook against live traffic without blocking anything. Your AI security server receives governed prompts and returns verdicts exactly as it would when enforcing, but nothing is blocked: every request proceeds to the model, even when your server denies it or can't be reached, and the end user sees nothing. Use it to tune your policy against your organization's real traffic before you start enforcing. With **Validate tool calls** on, your server also receives tool call frames in shadow mode, and no tool call is blocked.
104Shadow mode runs your hook against live traffic without blocking anything. Your AI security server receives governed prompts and returns verdicts exactly as it would when enforcing, but nothing is blocked: every request proceeds to the model, even when your server denies it or can’t be reached, and the end user sees nothing. Use it to tune your policy against your organization’s real traffic before you start enforcing. With **Validate tool calls** on, your server also receives tool call frames in shadow mode, and no tool call is blocked.
105105
106106To use shadow mode, set **Mode** to **Shadow mode** under **Failure handling**, then turn on **Enforce verdicts** so prompts flow to your AI security server. While it is active, the settings page shows a **Shadow mode — not blocking** badge. To leave shadow mode, set **Mode** back to **Allow the request** or **Block the request**; verdicts are enforced again once enforcement is on.
107107
108108## Exclusions
109109
110Under **Exclusions**, select roles whose members are not covered by Inference hooks: their prompts are never sent to your AI security server. Only custom roles your organization created can be excluded; the built-in roles aren't offered. Select them in the role selector, whose placeholder reads **Select roles to exclude**, and manage who holds each role from the roles admin page (**Manage roles**); changing exclusions requires identity management permission. The list is empty by default, and with no roles excluded, every governed request is inspected.
110Under **Exclusions**, select roles whose members are not covered by Inference hooks: their prompts are never sent to your AI security server. Only custom roles your organization created can be excluded; the built-in roles aren’t offered. Select them in the role selector, whose placeholder reads **Select roles to exclude**, and manage who holds each role from the roles admin page (**Manage roles**); changing exclusions requires identity management permission. The list is empty by default, and with no roles excluded, every governed request is inspected.
111111
112Exclusion applies to a user's interactive sessions. Changes to the exclusion list are recorded in your organization's [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) as role permission changes (`rbac_role_permission_added` and `rbac_role_permission_removed`).
112Exclusion applies to a user’s interactive sessions. Changes to the exclusion list are recorded in your organization’s [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) as role permission changes (`rbac_role_permission_added` and `rbac_role_permission_removed`).
113113
114114## Custom blocked prompt message
115115
116Under **Custom blocked prompt message**, set custom text of up to 500 characters that is appended to the error an end user sees when your AI security server denies a request (typically who to contact or where to request an exception). The final message is your AI security server's per-request `deny_reason` (when present), a blank line, then this text. With no custom text configured, a built-in default directs the user to contact their administrators; you can also switch the appended message off entirely so the user sees only the `deny_reason`.
116Under **Custom blocked prompt message**, set custom text of up to 500 characters that is appended to the error an end user sees when your AI security server denies a request (typically who to contact or where to request an exception). The final message is your AI security server’s per-request `deny_reason` (when present), a blank line, then this text. With no custom text configured, a built-in default directs the user to contact their administrators; you can also switch the appended message off entirely so the user sees only the `deny_reason`.
117117
118118## Monitor your AI security server
119119
from line 121
121121
122122* **Endpoint status:** Healthy, Tripped, Not enforcing, or Not configured before an endpoint is saved.
123123* **Failures per minute:** webhook failures over the last 2 minutes, averaged.
124* **Block rate:** denials as a share of your AI security server's verdicts, shown while the rollout percentage is below 100.
124* **Block rate:** denials as a share of your AI security server’s verdicts, shown while the rollout percentage is below 100.
125125* **Circuit breaker tripped:** when the breaker last tripped, if it has.
126* **Recent errors:** each entry shows when the failure occurred, an error type, and a category. The category is `webhook_error` for a problem with your endpoint or the connection to it, or `relay_error` for a failure inside Anthropic's systems. Entries never include request content or your endpoint URL. The list keeps the 10 most recent failures and clears an hour after the last one.
126* **Recent errors:** each entry shows when the failure occurred, an error type, and a category. The category is `webhook_error` for a problem with your endpoint or the connection to it, or `relay_error` for a failure inside Anthropic’s systems. A `DlpWebhookStatusError` entry can also show the HTTP status your AI security server returned and the size of the request body Anthropic sent, such as `HTTP 413` · `1.3 MB`. Entries never include request content or your endpoint URL. The list keeps the 10 most recent failures and clears an hour after the last one.
127127
128128The error types in **Recent errors** mean:
129129
130130| Error shown | What it means | Counts toward the circuit breaker |
131131| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
132| `DlpWebhookTimeoutError` · `webhook_error` | Your AI security server didn't return a verdict within the **Prompt verdict timeout (ms)** you set. | Yes |
132| `DlpWebhookTimeoutError` · `webhook_error` | Your AI security server didn’t return a verdict within the **Prompt verdict timeout (ms)** you set. | Yes |
133133| `DlpWebhookStatusError` · `webhook_error` | Your AI security server answered with an HTTP status other than 200, such as a redirect. | Yes |
134| `DlpWebhookResponseError` · `webhook_error` | Your AI security server answered 200, but the body isn't a valid verdict or is larger than 64 KiB. | Yes |
135| `DlpWebhookTransportError` · `webhook_error` | The connection failed or dropped before a complete answer arrived: for example, the hostname didn't resolve or resolved to a private address, the connection was refused or reset, or the TLS handshake failed. A network problem on Anthropic's side can also show up this way. | No |
136| `DlpWebhookDisallowedAddressError` · `webhook_error` | The endpoint URL's host is a private or internal IP address, an IPv6 address, or `localhost`. A hostname that resolves to such an address shows as a transport error instead. | Yes |
137| `DlpWebhookBlockedError` · `webhook_error` | The endpoint URL isn't an `https://` URL on port 443, or can't be parsed, so no request was sent. | No |
138| `DlpWebhookRelayError` · `relay_error` | The failure was inside Anthropic's systems, and your AI security server usually wasn't contacted. | No |
134| `DlpWebhookResponseError` · `webhook_error` | Your AI security server answered 200, but the body isn’t a valid verdict or is larger than 64 KiB. | Yes |
135| `DlpWebhookTransportError` · `webhook_error` | The connection failed or dropped before a complete answer arrived: for example, the hostname didn’t resolve or resolved to a private address, the connection was refused or reset, or the TLS handshake failed. A network problem on Anthropic’s side can also show up this way. | No |
136| `DlpWebhookDisallowedAddressError` · `webhook_error` | The endpoint URL’s host is a private or internal IP address, an IPv6 address, or `localhost`. A hostname that resolves to such an address shows as a transport error instead. | Yes |
137| `DlpWebhookBlockedError` · `webhook_error` | The endpoint URL isn’t an `https://` URL on port 443, or can’t be parsed, so no request was sent. | No |
138| `DlpWebhookRelayError` · `relay_error` | The failure was inside Anthropic’s systems, and your AI security server usually wasn’t contacted. | No |
139139
140140In shadow mode, no error counts toward the circuit breaker.
141141
from line 145
145145
146146Sustained webhook failures attributable to your AI security server trip the circuit breaker, which stops enforcement: your server is no longer contacted, and your **Failure handling** choice applies to every inspected request. With **Block the request** selected, users in your organization are blocked until the breaker resets. When the breaker trips, administrators are also notified in the claude.ai notification center.
147147
148Each trip is also recorded in your organization's [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) as an `inference_hooks_circuit_breaker_tripped` activity, so your security team or vendor can alert on trips from monitoring they already run, such as a SIEM that ingests the feed. One activity is recorded for each trip, not one for each affected request. Recording requires the Compliance API to be enabled for your organization; see [Set up the Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api-access).
148Each trip is also recorded in your organization’s [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) as an `inference_hooks_circuit_breaker_tripped` activity, so your security team or vendor can alert on trips from monitoring they already run, such as a SIEM that ingests the feed. One activity is recorded for each trip, not one for each affected request. Recording requires the Compliance API to be enabled for your organization; see [Set up the Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api-access).
149149
150150To recover, fix the server, then turn **Enforce verdicts** back on to reset the breaker.
151151
from line 161
161161
162162## Audit trail
163163
164Inference hooks activity is recorded in your organization's [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed): configuration changes, denials, circuit breaker trips, and requests that proceeded without inspection because no verdict could be obtained. That last kind is recorded only while **Enforce verdicts** is on and **Mode** is **Allow the request**. Its reason is `endpoint_timeout`, `endpoint_error` for any other problem calling your AI security server, or `internal_error` for a failure on Anthropic's side. Under **Block the request** or **Shadow mode**, failed requests aren't recorded individually. The circuit breaker's automatic recovery isn't recorded in any mode. While the circuit breaker is tripped, no per-request Inference hooks activities are recorded; the trip activity is the feed's record of that window. Denial records carry identifiers that let you join each denial to the matching record in your own system.
164Inference hooks activity is recorded in your organization’s [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed): configuration changes, denials, circuit breaker trips, and requests that proceeded without inspection because no verdict could be obtained. That last kind is recorded only while **Enforce verdicts** is on and **Mode** is **Allow the request**. Its reason is `endpoint_timeout`, `endpoint_error` for any other problem calling your AI security server, or `internal_error` for a failure on Anthropic’s side. Under **Block the request** or **Shadow mode**, failed requests aren’t recorded individually. The circuit breaker’s automatic recovery isn’t recorded in any mode. While the circuit breaker is tripped, no per-request Inference hooks activities are recorded; the trip activity is the feed’s record of that window. Denial records carry identifiers that let you join each denial to the matching record in your own system.
165165
166166## Turn Inference hooks off
167167
No line in this hunk matches that.