---
title: Configurar Inference hooks
url: https://platform.claude.com/docs/es/manage-claude/inference-hooks-configuration
description: Permite Inference hooks para tu organización de Claude Enterprise, conecta tu servidor de seguridad de IA y controla la aplicación de veredictos, el manejo de fallos y el despliegue gradual.
---
Inference hooks está en beta y disponible para organizaciones de Claude Enterprise. Configurarlo requiere el permiso `organization:manage`, que solo tienen los roles Owner y Primary owner.
Los "Inference hooks" (hooks de inferencia) envían los prompts de tu organización a un servidor de seguridad de IA que tú eliges, y retienen cada solicitud hasta recibir un veredicto de permitir o denegar antes de que Claude la procese. Esta página explica cómo activar la función, conectar tu servidor y controlar la aplicación de veredictos. Para saber qué son los Inference hooks y cuándo usarlos, consulta la [descripción general de Inference hooks](https://platform.claude.com/docs/es/manage-claude/inference-hooks). Para construir el servidor de seguridad de IA en sí, consulta [Desarrollar una integración de Inference hooks](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint).
## Antes de comenzar
Necesitas:
* El permiso `organization:manage` en claude.ai, que solo tienen los roles **Owner** y **Primary owner**. El rol **Admin** no lo tiene.
* Un endpoint HTTPS de servidor de seguridad de IA que acepte solicitudes de veredicto: una URL `https://` en el puerto 443, en un host enrutable públicamente y accesible sin redirecciones. Los hosts de túnel inverso (ngrok y servicios de túnel similares) no son compatibles: la política de red de Anthropic los bloquea. No hagas pruebas a través de un túnel; aloja tu servidor en un dominio que controles. Para conocer todos los [requisitos de alojamiento](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint#receive-a-request), y para crear el servidor y verificar las solicitudes firmadas, consulta [Desarrollar una integración de Inference hooks](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint).
## Configurar Inference hooks
Hay tres estados de aplicación: **desactivado** (**Aplicar veredictos** está desactivado: nunca se contacta a tu servidor de seguridad de IA y los prompts no se inspeccionan), **sombra** (**Aplicar veredictos** está activado con **Modo** establecido en **Modo sombra**: tu servidor de seguridad de IA recibe los prompts y devuelve veredictos, y no se bloquea nada) y **aplicando** (**Aplicar veredictos** está activado con **Modo** establecido en **Permitir la solicitud** o **Bloquear la solicitud**: una denegación bloquea la solicitud). Los siguientes pasos llevan una configuración nueva de desactivado a aplicando.
Ve a claude.ai > **Configuración de la organización** > **Datos y privacidad** y busca la sección **Inference hooks**. Activa **Permitir para tu organización**.
Activar esto desbloquea la página de configuración de Inference hooks y siempre fuerza **Aplicar veredictos** a desactivado, de modo que permitir la función nunca inicia la inspección por sí sola: incluso una configuración que anteriormente tenía la aplicación activada permanece sin inspección hasta que vuelvas a activar **Aplicar veredictos** en el paso final.
Aún en **Datos y privacidad**, abre la sección **Inference hooks** para llegar a la página de configuración de Inference hooks. Se encuentra dentro de Datos y privacidad en lugar de ser una entrada propia en la navegación de configuración, por lo que su ruta de navegación dice **Datos y privacidad / Inference hooks**. Hasta que guardes un endpoint, la página advierte que los prompts aún no se están inspeccionando, y **Aplicar veredictos** permanece desactivado con una insignia **Requiere endpoint**.
Haz clic en **Configure** para abrir el cuadro de diálogo **Set up endpoint** e ingresa la **Endpoint URL**: la URL `https://` que recibe las solicitudes de veredicto. Solo se aceptan URLs `https://`.
En este punto, el cuadro de diálogo no pide nada más: los encabezados de solicitud personalizados se configuran en el paso 5 y el manejo de fallos en el paso 6. Haz clic en **Next** para guardar. Una vez guardado un endpoint, el botón dice **Edit**.
El primer guardado genera tu "signing secret" (secreto de firma) de webhook y lo muestra una sola vez. Cópialo y guárdalo de forma segura antes de hacer clic en **Next**: el secreto no se puede recuperar más tarde, solo [rotar](https://platform.claude.com/docs/es/manage-claude/inference-hooks-configuration#rotate-your-signing-secret).
Tu servidor de seguridad de IA usa este secreto para verificar la firma de cada solicitud que recibe, incluida la prueba de conexión del siguiente paso. Para conocer el procedimiento de verificación, consulta [Verificar la firma](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint#verify-the-signature).
Al hacer clic en **Next** en el cuadro de diálogo del secreto de firma, se vuelve a abrir el cuadro de diálogo del endpoint, ahora con dos controles más:
* **Custom request headers:** hasta 16 encabezados estáticos que se envían con cada solicitud de veredicto para que tu servidor de seguridad de IA pueda autenticar a quien llama. Los valores de los encabezados se almacenan cifrados y nunca se vuelven a mostrar; después de guardar, solo se muestran los nombres de los encabezados. Como los valores son de solo escritura, guardar cualquier cambio en los encabezados requiere volver a ingresar todos los valores. Cambiar la URL del endpoint borra todos los valores de encabezado almacenados para que tus credenciales nunca se envíen a un destino nuevo; vuelve a ingresarlos después de cambiar la URL. Los nombres de los encabezados deben usar caracteres de token HTTP estándar con `-` en lugar de `_`, y no deben coincidir con nombres reservados (encabezados de estructura de solicitud como `Content-*` y `Host`, encabezados de proxy y de cookies, encabezados de dirección del cliente como `X-Forwarded-*`, los encabezados de firma `webhook-*` y el prefijo `X-Anthropic-*`). Los valores deben ser ASCII imprimible.
* **Test connection:** Claude envía un prompt de prueba sintético a la URL y los encabezados que están actualmente en el formulario, no a los valores guardados, así que vuelve a ingresar los valores de encabezado almacenados antes de probar. Si la prueba tiene éxito, el resultado indica si tu servidor de seguridad de IA devolvió un veredicto de permitir o de denegar para el prompt de prueba, lo que revela un comportamiento predeterminado de denegarlo todo antes de que empieces a aplicar veredictos.
Haz clic en **Save** para guardar los encabezados que ingresaste.
Resultados de fallo comunes:
| Resultado | Qué revisar |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL rechazada | La URL no superó una verificación estructural. Usa una URL `https://` en el puerto 443. |
| IP privada o interna | El host de la URL es una dirección IP privada o interna, una dirección IPv6 o `localhost`. Usa un host enrutable públicamente. |
| Tiempo de espera agotado | El servidor de seguridad de IA no devolvió un veredicto dentro del tiempo de espera. |
| Error de transporte | Falló la resolución DNS, el handshake TLS o la conexión, o el nombre de host se resuelve a una dirección privada. |
| Estado distinto de 200 | El servidor de seguridad de IA respondió con un estado distinto de 200. Los veredictos deben devolverse como HTTP 200; las redirecciones no se siguen y cuentan como fallos. |
| Respuesta no analizable | El servidor de seguridad de IA respondió, pero el cuerpo no es un veredicto válido. |
| Se requiere secreto de firma | Tu organización no tiene un secreto de firma, por lo que la prueba se enviaría sin firmar. Haz clic en **Generate secret** en **Request signing** y vuelve a probar. |
En **Manejo de fallos**, establece **Modo** para elegir qué sucede mientras el servidor de seguridad de IA no está accesible o los veredictos agotan el tiempo de espera:
* **Bloquear la solicitud:** detener la inferencia cuando tu servidor de seguridad de IA no puede entregar un veredicto (fallo cerrado).
* **Permitir la solicitud:** dejar que la solicitud continúe hacia el modelo sin inspección (fallo abierto).
La tercera opción del menú desplegable, **Modo sombra**, es una herramienta de despliegue gradual más que una política de fallos; consulta [Modo sombra](https://platform.claude.com/docs/es/manage-claude/inference-hooks-configuration#shadow-mode).
Luego establece **Tiempo de espera del veredicto del prompt (ms)**: de 1 a 10,000 ms, con un valor predeterminado de 5,000 ms. El presupuesto cubre todo el intercambio, y un veredicto más lento cuenta como un servidor inaccesible, así que establece el valor más bajo que tu servidor pueda cumplir de forma confiable.
Los cambios en esta sección se guardan a medida que los haces. En el primer guardado, los valores predeterminados son **Permitir la solicitud** y 5,000 ms.
En **Despliegue**, establece **Solicitudes inspeccionadas (%)** para ejecutar la inspección en un porcentaje de las solicitudes mientras pones en marcha tu servidor de seguridad de IA. El valor va de 0 a 100: 100 inspecciona todo y 0 desactiva la inspección.
Cada solicitud se sortea una vez para todo su turno de conversación, por lo que una misma conversación puede inspeccionarse parcialmente a lo largo de los turnos. Las solicitudes fuera del porcentaje muestreado continúan sin inspección, incluso cuando el manejo de fallos está establecido en **Bloquear la solicitud**.
Para evaluar los veredictos contra tráfico real sin bloquear a nadie al principio, establece **Modo** en **Modo sombra** (paso 6) antes de activar la aplicación; consulta [Modo sombra](https://platform.claude.com/docs/es/manage-claude/inference-hooks-configuration#shadow-mode).
Activa **Aplicar veredictos** para condicionar a Claude al veredicto de tu servidor de seguridad de IA en cada prompt gobernado y luego confirma en el cuadro de diálogo, que repite tu elección de manejo de fallos. Espera aproximadamente un minuto para que el cambio llegue a todos los servidores de Anthropic; las solicitudes que ya están en curso terminan con la configuración anterior. Desactivarlo hace que los prompts dejen de enviarse a tu servidor de seguridad de IA, también en aproximadamente un minuto; tu configuración se conserva.
**Validar llamadas a herramientas**, debajo de **Aplicar veredictos**, también envía las llamadas a herramientas de cada respuesta de Claude a tu servidor de seguridad de IA y espera su veredicto antes de que se ejecuten; consulta [El marco de llamada a herramienta](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint#the-tool-call-frame). Está activado de forma predeterminada en una configuración nueva. No tiene efecto mientras **Aplicar veredictos** está desactivado, y un cambio en esta opción tarda aproximadamente un minuto en llegar a todos los servidores de Anthropic, igual que con **Aplicar veredictos**.
## Modo sombra
El "shadow mode" (modo sombra) ejecuta tu hook con tráfico real sin bloquear nada. Tu servidor de seguridad de IA recibe los prompts gobernados y devuelve veredictos exactamente como lo haría al aplicarlos, pero no se bloquea nada: cada solicitud continúa hacia el modelo, incluso cuando tu servidor la deniega o no se puede contactar, y el usuario final no ve nada. Úsalo para ajustar tu política con el tráfico real de tu organización antes de empezar a aplicar los veredictos. Con **Validar llamadas a herramientas** activado, tu servidor también recibe marcos de llamadas a herramientas en modo sombra, y no se bloquea ninguna llamada a herramienta.
Para usar el modo sombra, establece **Modo** en **Modo sombra** en **Manejo de fallos**, y luego activa **Aplicar veredictos** para que los prompts fluyan hacia tu servidor de seguridad de IA. Mientras está activo, la página de configuración muestra una insignia **Modo sombra — sin bloqueo**. Para salir del modo sombra, vuelve a establecer **Modo** en **Permitir la solicitud** o **Bloquear la solicitud**; los veredictos se aplican de nuevo una vez que la aplicación está activada.
## Exclusiones
En **Exclusiones**, selecciona los roles cuyos miembros no están cubiertos por Inference hooks: sus prompts nunca se envían a tu servidor de seguridad de IA. Solo se pueden excluir los roles personalizados que tu organización creó; los roles integrados no se ofrecen. Elígelos en el selector de roles, cuyo texto de marcador dice **Seleccionar roles para excluir**, y administra quién posee cada rol desde la página de administración de roles (**Administrar roles**); cambiar las exclusiones requiere permiso de administración de identidades. La lista está vacía de forma predeterminada y, sin roles excluidos, se inspecciona cada solicitud gobernada.
La exclusión se aplica a las sesiones interactivas de un usuario. Los cambios en la lista de exclusiones se registran en el [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) de tu organización como cambios de permisos de roles (`rbac_role_permission_added` y `rbac_role_permission_removed`).
## Mensaje personalizado de prompt bloqueado
En **Mensaje personalizado de prompt bloqueado**, establece un texto personalizado de hasta 500 caracteres que se añade al error que ve un usuario final cuando tu servidor de seguridad de IA deniega una solicitud (normalmente a quién contactar o dónde solicitar una excepción). El mensaje final es el `deny_reason` por solicitud de tu servidor de seguridad de IA (cuando está presente), una línea en blanco y luego este texto. Sin texto personalizado configurado, un valor predeterminado integrado indica al usuario que contacte a sus administradores; también puedes desactivar por completo el mensaje añadido para que el usuario vea solo el `deny_reason`.
## Monitorear tu servidor de seguridad de IA
El área de estado del endpoint de la página de configuración de Inference hooks muestra:
* **Estado del endpoint:** Saludable, Disparado, Sin aplicar o Sin configurar antes de que se guarde un endpoint.
* **Fallos por minuto:** fallos del webhook en los últimos dos minutos, promediados.
* **Tasa de bloqueo:** denegaciones como proporción de los veredictos de tu servidor de seguridad de IA, que se muestra mientras el porcentaje de despliegue es inferior a 100.
* **Interruptor de circuito disparado:** cuándo se disparó el interruptor por última vez, si es que se disparó.
* **Errores recientes:** cada entrada muestra cuándo ocurrió el fallo, un tipo de error y una categoría. La categoría es `webhook_error` para un problema con tu endpoint o con la conexión a él, o `relay_error` para un fallo dentro de los sistemas de Anthropic. Las entradas nunca incluyen el contenido de la solicitud ni la URL de tu endpoint. La lista conserva los 10 fallos más recientes y se borra una hora después del último.
Los tipos de error en **Errores recientes** significan:
| Error mostrado | Qué significa | Cuenta para el disyuntor |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `DlpWebhookTimeoutError` · `webhook_error` | Tu servidor de seguridad de IA no devolvió un veredicto dentro del **Tiempo de espera del veredicto del prompt (ms)** que estableciste. | Sí |
| `DlpWebhookStatusError` · `webhook_error` | Tu servidor de seguridad de IA respondió con un estado HTTP distinto de 200, como una redirección. | Sí |
| `DlpWebhookResponseError` · `webhook_error` | Tu servidor de seguridad de IA respondió 200, pero el cuerpo no es un veredicto válido o supera los 64 KiB. | Sí |
| `DlpWebhookTransportError` · `webhook_error` | La conexión falló o se interrumpió antes de que llegara una respuesta completa: por ejemplo, el nombre de host no se resolvió o se resolvió a una dirección privada, la conexión fue rechazada o restablecida, o falló el handshake TLS. Un problema de red del lado de Anthropic también puede aparecer de esta forma. | No |
| `DlpWebhookDisallowedAddressError` · `webhook_error` | El host de la URL del endpoint es una dirección IP privada o interna, una dirección IPv6 o `localhost`. Un nombre de host que se resuelve a una dirección de ese tipo aparece en cambio como un error de transporte. | Sí |
| `DlpWebhookBlockedError` · `webhook_error` | La URL del endpoint no es una URL `https://` en el puerto 443, o no se puede analizar, por lo que no se envió ninguna solicitud. | No |
| `DlpWebhookRelayError` · `relay_error` | El fallo ocurrió dentro de los sistemas de Anthropic, y normalmente no se contactó a tu servidor de seguridad de IA. | No |
En modo sombra, ningún error cuenta para el disyuntor.
El panel funciona en modo de mejor esfuerzo: si Anthropic no puede leer los contadores, muestra cero fallos y ningún error en lugar de un error propio, por lo que un panel de aspecto saludable no es por sí mismo prueba de que tu servidor de seguridad de IA esté saludable. **Fallos por minuto** cuenta cada fallo, incluidos los errores de red y DNS que nunca disparan el interruptor de circuito, por lo que puede ser alto mientras **Interruptor de circuito disparado** permanece vacío.
## Interruptor de circuito
Los fallos de webhook sostenidos atribuibles a tu servidor de seguridad de IA disparan el "circuit breaker" (interruptor de circuito), que detiene la aplicación: ya no se contacta a tu servidor, y tu elección de **Manejo de fallos** se aplica a cada solicitud inspeccionada. Con **Bloquear la solicitud** seleccionado, los usuarios de tu organización quedan bloqueados hasta que el interruptor se restablezca. Cuando el interruptor se dispara, también se notifica a los administradores en el centro de notificaciones de claude.ai.
Cada disparo también se registra en el [Feed de actividad](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) de tu organización como una actividad `inference_hooks_circuit_breaker_tripped`, para que tu equipo de seguridad o proveedor pueda generar alertas sobre los disparos desde el monitoreo que ya ejecutan, como un SIEM que ingiere el feed. Se registra una actividad por disparo, no una por solicitud afectada. El registro requiere que la Compliance API esté habilitada para tu organización; consulta [Configurar la Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api-access).
Para recuperarte, corrige el servidor y luego vuelve a activar **Aplicar veredictos** para restablecer el interruptor.
El disyuntor también puede restablecerse por sí solo. A partir de 10 minutos después de la activación, Anthropic comprueba si tu servidor se ha recuperado enviándole una solicitud de prueba en segundo plano, como máximo aproximadamente una vez por minuto; no interviene ninguna solicitud de usuario. Si tu servidor responde con un veredicto válido, de permitir o de denegar, el disyuntor se restablece y la aplicación se reanuda. De lo contrario, el disyuntor permanece activado y las comprobaciones continúan.
La recuperación automática solo se ejecuta mientras tu configuración de Inference hooks no haya cambiado desde la activación. Si cambias cualquier configuración de Inference hooks después de una activación, incluida la rotación del secreto de firma, las comprobaciones se detienen y el disyuntor ya no se restablece por sí solo; vuelve a activar **Enforce verdicts** cuando tu servidor esté corregido. La recuperación automática solo se aplica a las activaciones del disyuntor: si tú mismo desactivas **Enforce verdicts**, la aplicación permanece desactivada hasta que la vuelvas a activar.
## Rotar tu secreto de firma
Haz clic en **Rotate secret** en **Request signing** para reemplazar tu secreto de firma. Si tu organización aún no tiene un secreto, el mismo botón dice **Generate secret** y crea el primero. La rotación es un cambio inmediato: el nuevo secreto se genera y se muestra una sola vez, el secreto anterior ya no se puede recuperar y ninguna solicitud se firma nunca con ambos secretos, por lo que no hay un período de superposición en el que puedas confiar.
Las solicitudes firmadas con el secreto anterior aún pueden llegar brevemente después de la rotación; [Verificar la firma](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint#verify-the-signature) cubre cómo tu servidor de seguridad de IA debe manejar la transición.
## Registro de auditoría
La actividad de Inference hooks se registra en el [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) de tu organización: cambios de configuración, denegaciones, activaciones del disyuntor y solicitudes que continuaron sin inspección porque no se pudo obtener un veredicto. Este último tipo solo se registra mientras **Aplicar veredictos** está activado y **Modo** es **Permitir la solicitud**. Su motivo es `endpoint_timeout`, `endpoint_error` para cualquier otro problema al llamar a tu servidor de seguridad de IA, o `internal_error` para un fallo del lado de Anthropic. Con **Bloquear la solicitud** o **Modo sombra**, las solicitudes fallidas no se registran individualmente. La recuperación automática del disyuntor no se registra en ningún modo. Mientras el disyuntor está activado, no se registran actividades de Inference hooks por solicitud; la actividad de activación es el registro del feed para ese período. Los registros de denegación incluyen identificadores que te permiten vincular cada denegación con el registro correspondiente en tu propio sistema.
## Desactivar Inference hooks
Hay dos niveles de desactivación:
* **Aplicar veredictos** desactivado, en la página de configuración de Inference hooks: en aproximadamente un minuto, los prompts de tu organización dejan de enviarse a tu servidor de seguridad de IA; las solicitudes ya en curso terminan con la configuración anterior. La página de configuración sigue disponible, así que usa esto para pausar la aplicación mientras trabajas en tu servidor de seguridad de IA.
* **Permitir para tu organización** desactivado, en la configuración de **Datos y privacidad**: los prompts ya no se inspeccionan, y la configuración de Inference hooks deja de estar disponible hasta que lo vuelvas a activar. Tu configuración de endpoint, encabezados personalizados y secreto de firma se conservan en cualquier caso; volver a activarlo fuerza **Aplicar veredictos** a desactivado y borra un interruptor de circuito disparado, así que activa la aplicación de nuevo cuando estés listo.
## Próximos pasos
Construye el servidor de seguridad de IA: los esquemas de solicitud y veredicto, la verificación de firmas y la semántica operativa.
Qué son los Inference hooks, cómo funciona el ciclo de ida y vuelta del veredicto y qué se envía a tu servidor de seguridad de IA.