--- title: Configurar hooks de inferencia url: https://platform.claude.com/docs/es/manage-claude/inference-hooks-configuration description: Permite los hooks de inferencia 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. --- Los hooks de inferencia están disponibles solo para organizaciones de Claude Enterprise. Configurarlos requiere el permiso `organization:manage`, que solo tienen los roles Propietario y Propietario principal. 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 empezar Necesitas: * El permiso `organization:manage` en claude.ai, que solo tienen los roles **Propietario** y **Propietario principal**. El rol **Administrador** 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 hooks de inferencia](https://platform.claude.com/docs/es/manage-claude/inference-hooks-endpoint). ## Configurar hooks de inferencia Hay tres estados de aplicación: * **Desactivado:** con **Aplicar veredictos** desactivado, nunca se contacta a tu servidor de seguridad de IA y los prompts no se inspeccionan. * **Sombra:** con **Aplicar veredictos** activado y **Modo** establecido en **Modo sombra**, tu servidor de seguridad de IA recibe los prompts y devuelve veredictos, y no se bloquea nada. * **Aplicando:** con **Aplicar veredictos** activado y **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 desactivada a aplicando. Ve a claude.ai > **Configuración de la organización** > **Datos y privacidad** y busca la sección **Hooks de inferencia**. Activa **Permitir para su organización**. Activar esto desbloquea la página de configuración de los hooks de inferencia 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. Todavía en **Datos y privacidad**, abre la sección **Hooks de inferencia** para llegar a la página de configuración de los hooks de inferencia. Se encuentra dentro de **Datos y privacidad** en lugar de tener su propia entrada en la navegación de configuración, por lo que su ruta de navegación muestra **Datos y privacidad / Hooks de inferencia**. 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 **Configurar** para abrir el cuadro de diálogo **Configurar endpoint** e introduce la **URL del endpoint**: 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 llegan en el paso 5, y el manejo de fallos en el paso 6. Haz clic en **Siguiente** para guardar. Una vez guardado un endpoint, el botón muestra **Editar**. 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 **Siguiente**: 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 **Siguiente** 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: * **Encabezados de solicitud personalizados:** 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. * **Probar conexión:** 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. También muestra el tiempo de ida y vuelta que Anthropic midió para esa única solicitud de prueba, en una conexión nueva, incluido el handshake de conexión. Haz clic en **Guardar** 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 **Generar secreto** en **Firma de solicitudes** y vuelve a probar. | En **Manejo de fallos**, establece **Modo** para elegir qué ocurre 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 y no 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 para cada prompt gobernado, y luego confirma en el cuadro de diálogo, que vuelve a indicar tu elección de manejo de fallos. Espera aproximadamente un minuto a que el cambio llegue a todos los servidores de Anthropic; las solicitudes que ya están en curso se completan con la configuración anterior. Desactivarlo detiene el envío de prompts 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 bloqueos**. 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 **Who is inspected**, con **Limit by role** activado, selecciona los roles cuyos miembros no están cubiertos por los hooks de inferencia: sus prompts nunca se envían a tu servidor de seguridad de IA. Solo se pueden excluir los roles personalizados que creó tu organización; los roles integrados no se ofrecen. Selecciónalos en el selector de roles, cuyo texto de marcador dice **Seleccionar roles para excluir**, y administra quién tiene cada rol desde la página de administración de roles (**Gestionar roles**); cambiar las exclusiones requiere el permiso de administración de identidades. La lista está vacía de forma predeterminada y, sin roles excluidos, se inspecciona cada solicitud controlada, a menos que **Inspeccionar** esté establecido en **Only selected roles**. 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`). ### Inspeccionar solo los roles seleccionados Todo en la sección **Who is inspected** depende de un solo interruptor, **Limit by role**. Cuando activas el interruptor, **Inspeccionar** comienza en **Everyone except excluded roles**, y los roles excluidos se seleccionan debajo como se describió anteriormente. Para probar los hooks de inferencia primero en una parte de tu organización, activa **Limit by role**, establece **Inspeccionar** en **Only selected roles** y selecciona los roles en el cuadro de diálogo que se abre. A partir de entonces, solo se inspeccionan los miembros configurados con **Roles personalizados** que tienen asignado un rol seleccionado. Los miembros configurados con cualquier otro rol, como **Usuario** o **Propietario**, no se inspeccionan, aunque tengan asignado un rol seleccionado. Eso te incluye a ti si estás configurado como **Propietario** o **Propietario principal**. Elimina todos los roles excluidos antes de cambiar: una organización usa exclusiones o roles seleccionados, no ambos. Después del cambio, agrega o elimina roles en el selector de roles bajo **Inspeccionar**. Para volver a inspeccionar a todos, desactiva **Limit by role**: después de confirmar, esto elimina todos los roles excluidos y desactiva **Only selected roles**. Mientras **Only selected roles** está establecido: * Un rol personalizado cuyo **Acceso a capacidades** es **Todas las capacidades** o **Todo disponible de forma general** solo cuenta si lo seleccionas, como cualquier otro rol. * Si ningún miembro configurado con **Roles personalizados** tiene asignado un rol seleccionado, no se inspecciona a ningún miembro. * No se inspeccionan las solicitudes que no tienen un miembro detrás, como las solicitudes realizadas con claves de API y las conversaciones de Claude Tag en Slack. Los cambios en **Inspeccionar** y en los roles inspeccionados se registran en el [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-activity-feed) de tu organización. ## 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 los hooks de inferencia muestra: * **Estado del endpoint:** Saludable, Disparado, Sin aplicar o Sin configurar antes de que se guarde un endpoint. * **Fallas por minuto:** fallos del webhook durante los últimos 2 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 activado:** 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. Una entrada `DlpWebhookStatusError` también puede mostrar el estado HTTP que devolvió tu servidor de seguridad de IA y el tamaño del cuerpo de la solicitud que envió Anthropic, como `HTTP 413` · `1.3 MB`. 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. **Fallas por minuto** cuenta cada fallo, incluidos los errores de red y DNS que nunca disparan el interruptor de circuito, por lo que su valor puede ser alto mientras **Interruptor de circuito activado** 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 [Activity Feed](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 tu proveedor puedan generar alertas sobre los disparos desde la supervisión que ya utilizan, como un SIEM que ingiera el feed. Se registra una actividad por cada disparo, no una por cada 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 los hooks de inferencia no haya cambiado desde la activación. Si cambias cualquier configuración de los hooks de inferencia 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 **Aplicar veredictos** cuando tu servidor esté corregido. La recuperación automática solo se aplica a las activaciones del disyuntor: si tú mismo desactivas **Aplicar veredictos**, la aplicación permanece desactivada hasta que la vuelvas a activar. ## Rotar tu secreto de firma Haz clic en **Rotar secreto** en **Firma de solicitudes** para reemplazar tu secreto de firma. Si tu organización aún no tiene un secreto, el mismo botón dice **Generar secreto** 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 los hooks de inferencia 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 hooks de inferencia 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 los hooks de inferencia Hay dos niveles de desactivación: * **Aplicar veredictos** desactivado, en la página de configuración de los hooks de inferencia: en aproximadamente un minuto, los prompts de tu organización dejan de enviarse a tu servidor de seguridad de IA; las solicitudes que ya están en curso se completan con la configuración anterior. La página de configuración sigue disponible, así que usa esta opción para pausar la aplicación mientras trabajas en tu servidor de seguridad de IA. * **Permitir para su organización** desactivado, en la configuración de **Datos y privacidad**: los prompts ya no se inspeccionan, y la configuración de los hooks de inferencia 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 hooks de inferencia, cómo funciona el ciclo de ida y vuelta del veredicto y qué se envía a tu servidor de seguridad de IA.