Webhooks de la organización

Un "organization webhook endpoint" (endpoint de webhook de la organización) recibe un evento cuando Anthropic restringe o veta uno de los perfiles de usuario de tu organización, y cuando la restricción o el veto termina. Lo administras con la Admin API en /v1/organizations/webhooks.

Cualquier miembro de tu organización puede listar y ver los endpoints de webhook de la organización con la API, pero solo los miembros con el rol de administrador, propietario o propietario principal pueden crearlos, cambiarlos o eliminarlos, o reemplazar su "signing secret" (secreto de firma).

Antes de comenzar

Necesitas lo siguiente:

• Una organización en la Claude API que tenga los webhooks de la organización activados y que no tenga habilitada la preparación para HIPAA. Para solicitar acceso, contacta a tu equipo de cuenta de Anthropic.
• Una de estas credenciales:
  • Una clave de API de Admin.
  • Un token bearer de OAuth con el alcance org:admin.
  • Una clave personal o de cuenta de servicio que no esté limitada a un espacio de trabajo.

Tipos de eventos

Los endpoints de webhook de la organización aceptan dos tipos de eventos. Ambos tratan sobre "enforcement actions" (medidas de aplicación) en perfiles de usuario. Una medida de aplicación es una restricción o un veto que Anthropic impone al cliente final al que representa un perfil.

Eliminar un perfil pone fin a sus medidas abiertas sin un evento user_profile.enforcement_action_resolved.

Antes de tu primer evento

Tus perfiles no tendrán los campos enforcement_status y enforcement_actions hasta que las medidas de aplicación estén activadas para tu organización. Hasta entonces, y en cualquier solicitud cuyo encabezado anthropic-beta tenga user-profiles-2026-09-04 o un valor anterior, las respuestas omiten los campos y el filtro de lista enforcement_status[] devuelve un 400. Para obtener los campos, elimina ese valor de tus solicitudes.

Si una medida de aplicación se abrió antes de que Anthropic activara las medidas de aplicación y la entrega de eventos para tu organización, o antes de que registraras tu endpoint, no recibes un evento user_profile.enforcement_action_opened para ella. La medida sigue apareciendo en el perfil. Para encontrar estas medidas, lista tus perfiles con enforcement_status[]=restricted y enforcement_status[]=banned. Una respuesta podría devolver menos perfiles que limit, o ninguno, antes de que termine la lista, así que sigue solicitando páginas hasta que next_page sea null.

Qué contiene un evento

Los eventos contienen IDs, no la medida ni el perfil. data.id es el ID del perfil, y data.enforcement_action_id es el ID de la medida, que comienza con enac_:

{
  "type": "event",
  "id": "whe_4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c",
  "created_at": "2026-10-15T17:02:41Z",
  "data": {
    "type": "user_profile.enforcement_action_opened",
    "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    "enforcement_action_id": "enac_011CZkZEq4TnWb7xLfRgPm2v",
    "organization_id": "org_011CZkZBj9RsYd3wNcHvKq6t"
  }
}

Para ver qué cambió, recupera el perfil con client.user_profiles.retrieve(), usando data.id. Su lista enforcement_actions muestra sus medidas abiertas. Cada medida tiene un type (restriction o ban), un id, un reason, una hora opened_at y una hora expires_at o null. enforcement_status las resume: banned mientras hay un veto abierto, restricted mientras hay cualquier otra medida abierta, y unrestricted cuando no hay ninguna. Trata cualquier otro valor como restricted.

Anthropic envía un evento solo después de que el perfil muestra el cambio, por lo que el perfil que recuperas muestra ese cambio o uno posterior. Los eventos podrían llegar tarde o fuera de orden, así que usa el estado actual del perfil, no el orden en que llegan los eventos. Después de user_profile.enforcement_action_resolved, la medida resuelta ya no está en la lista. Un 404 significa que el perfil fue eliminado.

Campos del endpoint

Un endpoint de webhook de la organización tiene estos campos:

{
  "id": "wep_011CZkZDf8HnUq2mTxRbVn4s",
  "url": "https://example.com/anthropic-webhooks",
  "name": "Enforcement actions",
  "description": "",
  "enabled_events": [
    "user_profile.enforcement_action_opened",
    "user_profile.enforcement_action_resolved"
  ],
  "state": "enabled",
  "disabled_reason": "",
  "created_at": "2026-10-20T19:00:00Z",
  "updated_at": "2026-10-20T19:00:00Z"
}

Una organización puede tener hasta 32 endpoints de webhook de la organización. Los endpoints de webhook deshabilitados siguen contando para este total.

Entregas

Las entregas siguen la especificación Standard Webhooks. Cada una incluye los encabezados webhook-id, webhook-timestamp y webhook-signature. Antes de confiar en un evento, verifica su firma con el secreto de firma del endpoint, usando cualquier biblioteca de Standard Webhooks.

Devuelve cualquier estado 2xx en un plazo de 5 segundos y realiza el trabajo lento después. Cualquier otra respuesta, o la ausencia de respuesta, cuenta como un intento fallido.

• Duplicados: Un endpoint podría recibir el mismo evento más de una vez, con el mismo id de evento (el mismo valor que el encabezado webhook-id). Elimina duplicados basándote en él.

• Reintentos: Si una entrega falla, Anthropic la reintenta algunas veces durante los siguientes minutos. Si todos los intentos fallan, Anthropic descarta el evento. Para ponerte al día, lista tus perfiles por estado de las medidas de aplicación, como en Antes de tu primer evento.

• Deshabilitación automática: Anthropic deshabilita un endpoint cuando:

  • Devuelve una redirección (3xx).
  • Su URL se resuelve en una dirección IP no pública.
  • Sus entregas siguen fallando.

  Anthropic omite los eventos para un endpoint deshabilitado y no los envía más tarde.

Administrar endpoints

Con la Admin API, puedes hacer estas solicitudes:

En una actualización, enabled_events reemplaza toda la lista de tipos de eventos del endpoint. Una lista vacía no borra la lista: el endpoint conserva los tipos de eventos que tenía. Para detener las entregas, envía "state": "disabled" o elimina el endpoint.

Para volver a activar un endpoint, incluso después de que Anthropic lo haya deshabilitado, envía "state": "enabled" en una solicitud de actualización.

Cuando reemplazas el secreto de firma, el secreto anterior deja de funcionar de inmediato. Las entregas a partir de ese momento, incluidos los reintentos de eventos anteriores, se firman con el nuevo secreto, así que actualiza tu receptor de inmediato.

Envía el encabezado anthropic-beta: webhooks-2026-10-07 con cada solicitud. El SDK y la CLI lo envían por ti. Este ejemplo lista los endpoints de tu organización, usando una clave de API de Admin de ANTHROPIC_API_KEY.

client = anthropic.Anthropic()

endpoints = client.beta.organization.webhooks.list()

for endpoint in endpoints:
    print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})")

Sin endpoints, la API devuelve una lista vacía:

{
  "data": [],
  "has_more": false
}

Una lista devuelve hasta 20 endpoints de forma predeterminada. Establece limit para obtener hasta 100. Si has_more es true, pasa el last_id de la respuesta como after_id para obtener la página siguiente.

Este ejemplo crea un endpoint que recibe ambos tipos de eventos:

client = anthropic.Anthropic()

endpoint = client.beta.organization.webhooks.create(
    url="https://example.com/anthropic-webhooks",
    name="Enforcement actions",
    enabled_events=[
        "user_profile.enforcement_action_opened",
        "user_profile.enforcement_action_resolved",
    ],
)

print(endpoint.id)

La respuesta es el nuevo endpoint, como se muestra en Campos del endpoint, más su signing_secret.

Errores

Una solicitud devuelve un 400 si:

• Su url no cumple las reglas de Campos del endpoint, o una solicitud de creación no lista ningún tipo de evento. El mensaje de error indica qué está mal.
• Tu organización no tiene un espacio de trabajo predeterminado.
• Los webhooks de la organización no están disponibles para tu organización porque su espacio de trabajo predeterminado usa una clave de cifrado administrada por el cliente. El mensaje de error lo indica.
• Daría a tu organización más de 32 endpoints de webhook de la organización.
• Incluye en enabled_events un tipo de evento distinto de los dos de Tipos de eventos. El mensaje de error lista los tipos aceptados.

Una solicitud devuelve un 403 si el rol de tu cuenta no incluye el permiso que necesita la solicitud. El error nombra ese permiso.

Una solicitud devuelve un 404 si:

• No envía el encabezado anthropic-beta: webhooks-2026-10-07.
• Anthropic no ha activado los webhooks de la organización para tu organización.
• Tu organización tiene habilitada la preparación para HIPAA.
• Usa un tipo de credencial que estas solicitudes no aceptan.
• Su webhook_endpoint_id no coincide con un endpoint de tu organización.

Una solicitud devuelve un 409 si:

• Haría que dos endpoints de webhook de la organización habilitados compartieran una URL.
• Otra solicitud cambió los endpoints de tu organización al mismo tiempo. Reintenta la solicitud.

Compatibility