--- title: Webhooks de la organización url: https://platform.claude.com/docs/es/manage-claude/organization-webhooks description: Registra endpoints de webhook para eventos sobre medidas de aplicación en los perfiles de usuario de tu organización. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- 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](https://platform.claude.com/docs/es/manage-claude/user-profiles) de tu organización, y cuando la restricción o el veto termina. Lo administras con la Admin API en `/v1/organizations/webhooks`. La entrega de eventos no está activa: Anthropic no envía los dos eventos, por lo que un endpoint que registres no recibe nada. Puedes registrar endpoints y crear tu controlador a partir del formato de eventos de esta página. 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](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#hipaa-readiness). Para solicitar acceso, contacta a tu equipo de cuenta de Anthropic. * Una de estas credenciales: * Una [clave de API de Admin](https://platform.claude.com/docs/es/manage-claude/admin-api-keys). * Un [token bearer de OAuth](https://platform.claude.com/docs/es/manage-claude/admin-api#oauth-bearer-token) con el alcance `org:admin`. * Una [clave personal o de cuenta de servicio](https://platform.claude.com/docs/es/manage-claude/authentication#key-types) 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. | Evento | Desencadenante | | ------------------------------------------ | ------------------------------------------------------------------------------------- | | `user_profile.enforcement_action_opened` | Anthropic abre una medida de aplicación en un perfil de usuario. | | `user_profile.enforcement_action_resolved` | Una medida de aplicación termina. Anthropic la resuelve, o pasa su hora `expires_at`. | 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](https://platform.claude.com/docs/es/api/user_profiles/list) 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_`: ```json { "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](https://platform.claude.com/docs/es/api/user_profiles/retrieve) con `GET /v1/user_profiles/{id}` (python, ruby: `client.user_profiles.retrieve()`; typescript: `client.userProfiles.retrieve()`; go: `client.UserProfiles.Get()`; java: `client.userProfiles().retrieve()`; csharp: `client.UserProfiles.Retrieve()`; php: `$client->userProfiles->retrieve()`; cli: `ant 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: | Campo | Tipo | Descripción | | ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | El ID del endpoint, que comienza con `wep_`. Lo establece Anthropic. | | `url` | string | Dónde envía Anthropic los eventos. Debe ser HTTPS en el puerto 443, con un nombre de dominio público, no una dirección IP. Dos endpoints de webhook de la organización habilitados en tu organización no pueden compartir una URL. | | `enabled_events` | array de strings | Los [tipos de eventos](https://platform.claude.com/docs/es/manage-claude/organization-webhooks#event-types) que recibe este endpoint. Una solicitud de creación debe listar al menos uno. | | `name` | string | Una etiqueta opcional para tu propio uso. | | `description` | string | Una descripción opcional para tu propio uso. | | `state` | string | `enabled` o `disabled`. | | `disabled_reason` | string | Por qué Anthropic deshabilitó el endpoint. Vacío en caso contrario. | | `created_at` | string | Cuándo se creó el endpoint. Lo establece Anthropic. | | `updated_at` | string | Cuándo cambió el endpoint por última vez. Lo establece Anthropic. | | `signing_secret` | string | Un secreto con el prefijo `whsec_`, creado con el endpoint. Solo las respuestas que crean el endpoint o reemplazan el secreto lo incluyen, así que guárdalo de forma segura. | ```json { "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](https://www.standardwebhooks.com/). 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](https://platform.claude.com/docs/es/manage-claude/organization-webhooks#before-your-first-event). * **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: | Tarea | Solicitud | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Listar los endpoints de tu organización | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/list) | | Crear un endpoint | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/create) | | Obtener un endpoint | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/retrieve) | | Actualizar `url`, `name`, `description`, `enabled_events` o `state` de un endpoint | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/update) | | Eliminar un endpoint | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/delete) | | Reemplazar el secreto de firma | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/es/api/beta/organization/webhooks/regenerate_signing_secret) | 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`. ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" ``` ```bash CLI ant beta:organization:webhooks list ``` ```python Python client = anthropic.Anthropic() endpoints = client.beta.organization.webhooks.list() for endpoint in endpoints: print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})") ``` ```typescript TypeScript const client = new Anthropic(); const endpoints = await client.beta.organization.webhooks.list(); for await (const endpoint of endpoints) { console.log(`${endpoint.id}: ${endpoint.url} (${endpoint.state})`); } ``` ```csharp C# AnthropicClient client = new(); var page = await client.Beta.Organization.Webhooks.List(); await foreach (var endpoint in page.Paginate()) { Console.WriteLine($"{endpoint.ID}: {endpoint.Url} ({endpoint.State.Raw()})"); } ``` ```go Go client := anthropic.NewClient() endpoints := client.Beta.Organization.Webhooks.ListAutoPaging(context.Background(), anthropic.BetaOrganizationWebhookListParams{}) for endpoints.Next() { endpoint := endpoints.Current() fmt.Printf("%s: %s (%s)\n", endpoint.ID, endpoint.URL, endpoint.State) } if err := endpoints.Err(); err != nil { log.Fatal(err) } ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var endpoints = client.beta().organization().webhooks().list(); for (var endpoint : endpoints.autoPager()) { IO.println(endpoint.id() + ": " + endpoint.url() + " (" + endpoint.state().asString() + ")"); } ``` ```php PHP $client = new Client(); $endpoints = $client->beta->organization->webhooks->list(); foreach ($endpoints->pagingEachItem() as $endpoint) { echo "{$endpoint->id}: {$endpoint->url} ({$endpoint->state})\n"; } ``` ```ruby Ruby client = Anthropic::Client.new endpoints = client.beta.organization.webhooks.list endpoints.auto_paging_each do |endpoint| puts "#{endpoint.id}: #{endpoint.url} (#{endpoint.state})" end ``` Sin endpoints, la API devuelve una lista vacía: ```json { "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: ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" \ -H "content-type: application/json" \ -d '{ "url": "https://example.com/anthropic-webhooks", "name": "Enforcement actions", "enabled_events": [ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved" ] }' ``` ```bash CLI ant beta:organization:webhooks create \ --url https://example.com/anthropic-webhooks \ --name "Enforcement actions" \ --enabled-event user_profile.enforcement_action_opened \ --enabled-event user_profile.enforcement_action_resolved ``` ```python Python 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) ``` ```typescript TypeScript const client = new Anthropic(); const endpoint = await 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" ] }); console.log(endpoint.id); ``` ```csharp C# using Anthropic.Models.Beta.Organization.Webhooks; AnthropicClient client = new(); var endpoint = await client.Beta.Organization.Webhooks.Create(new WebhookCreateParams { UrlValue = "https://example.com/anthropic-webhooks", Name = "Enforcement actions", EnabledEvents = [ EnabledEvent.UserProfileEnforcementActionOpened, EnabledEvent.UserProfileEnforcementActionResolved, ], }); Console.WriteLine(endpoint.ID); ``` ```go Go client := anthropic.NewClient() endpoint, err := client.Beta.Organization.Webhooks.New(context.Background(), anthropic.BetaOrganizationWebhookNewParams{ URL: "https://example.com/anthropic-webhooks", Name: anthropic.String("Enforcement actions"), EnabledEvents: []string{ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved", }, }) if err != nil { log.Fatal(err) } fmt.Println(endpoint.ID) ``` ```java Java import com.anthropic.models.beta.organization.webhooks.WebhookCreateParams; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = WebhookCreateParams.builder() .url("https://example.com/anthropic-webhooks") .name("Enforcement actions") .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_OPENED) .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_RESOLVED) .build(); var endpoint = client.beta().organization().webhooks().create(params); IO.println(endpoint.id()); } ``` ```php PHP $client = new Client(); $endpoint = $client->beta->organization->webhooks->create( url: 'https://example.com/anthropic-webhooks', name: 'Enforcement actions', enabledEvents: [ 'user_profile.enforcement_action_opened', 'user_profile.enforcement_action_resolved', ], ); echo $endpoint->id, "\n"; ``` ```ruby Ruby client = Anthropic::Client.new 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" ] ) puts endpoint.id ``` La respuesta es el nuevo endpoint, como se muestra en [Campos del endpoint](https://platform.claude.com/docs/es/manage-claude/organization-webhooks#endpoint-fields), más su `signing_secret`. ## Errores Una solicitud devuelve un `400` si: * Su `url` no cumple las reglas de [Campos del endpoint](https://platform.claude.com/docs/es/manage-claude/organization-webhooks#endpoint-fields), 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](https://platform.claude.com/docs/es/manage-claude/cmek). 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](https://platform.claude.com/docs/es/manage-claude/organization-webhooks#event-types). 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.