--- title: Webhooks d'organisation url: https://platform.claude.com/docs/fr/manage-claude/organization-webhooks description: Enregistrez des points de terminaison de webhook pour recevoir des événements concernant les mesures d'application prises sur les profils utilisateur de votre organisation. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- Un « organization webhook endpoint » (point de terminaison de webhook d'organisation) reçoit un événement lorsqu'Anthropic restreint ou bannit l'un des [profils utilisateur](https://platform.claude.com/docs/fr/manage-claude/user-profiles) de votre organisation, et lorsque la restriction ou le bannissement prend fin. Vous le gérez avec l'Admin API sous `/v1/organizations/webhooks`. La livraison des événements n'est pas active : Anthropic n'envoie pas les deux événements, de sorte qu'un point de terminaison que vous enregistrez ne reçoit rien. Vous pouvez enregistrer des points de terminaison et construire votre gestionnaire à partir du format d'événement décrit sur cette page. Tout membre de votre organisation peut lister et consulter les points de terminaison de webhook d'organisation avec l'API, mais seuls les membres ayant le rôle admin, owner ou primary owner peuvent les créer, les modifier ou les supprimer, ou remplacer leur secret de signature. ## Avant de commencer Vous avez besoin des éléments suivants : * Une organisation sur la Claude API pour laquelle les webhooks d'organisation sont activés et pour laquelle la [préparation HIPAA](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention#hipaa-readiness) n'est pas activée. Pour demander l'accès, contactez votre équipe de compte Anthropic. * L'un de ces identifiants : * Une [clé Admin API](https://platform.claude.com/docs/fr/manage-claude/admin-api-keys). * Un [jeton porteur OAuth](https://platform.claude.com/docs/fr/manage-claude/admin-api#oauth-bearer-token) avec la portée `org:admin`. * Une [clé personnelle ou de compte de service](https://platform.claude.com/docs/fr/manage-claude/authentication#key-types) qui n'est pas limitée à un espace de travail. ## Types d'événements Les points de terminaison de webhook d'organisation acceptent deux types d'événements. Tous deux concernent des « enforcement actions » (mesures d'application) sur des profils utilisateur. Une mesure d'application est une restriction ou un bannissement qu'Anthropic impose au client final représenté par un profil. | Événement | Déclencheur | | ------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `user_profile.enforcement_action_opened` | Anthropic ouvre une mesure d'application sur un profil utilisateur. | | `user_profile.enforcement_action_resolved` | Une mesure d'application prend fin. Anthropic la résout, ou son heure `expires_at` est dépassée. | La suppression d'un profil met fin à ses mesures ouvertes sans événement `user_profile.enforcement_action_resolved`. ### Avant votre premier événement Vos profils n'auront pas les champs `enforcement_status` et `enforcement_actions` tant que les mesures d'application ne seront pas activées pour votre organisation. D'ici là, ainsi que dans toute requête dont l'en-tête `anthropic-beta` contient `user-profiles-2026-09-04` ou une valeur antérieure, les réponses omettent ces champs et le filtre de liste `enforcement_status[]` renvoie une erreur `400`. Pour obtenir ces champs, retirez cette valeur de vos requêtes. Si une mesure d'application a été ouverte avant qu'Anthropic n'active les mesures d'application et la livraison des événements pour votre organisation, ou avant que vous n'enregistriez votre point de terminaison, vous ne recevez pas d'événement `user_profile.enforcement_action_opened` pour celle-ci. La mesure apparaît tout de même sur le profil. Pour trouver ces mesures, [listez vos profils](https://platform.claude.com/docs/fr/api/user_profiles/list) avec `enforcement_status[]=restricted` et `enforcement_status[]=banned`. Une réponse peut renvoyer moins de profils que `limit`, voire aucun, avant la fin de la liste ; continuez donc à demander des pages jusqu'à ce que `next_page` soit `null`. ### Contenu d'un événement Les événements contiennent des ID, et non la mesure ou le profil. `data.id` est l'ID du profil, et `data.enforcement_action_id` est l'ID de la mesure, qui commence par `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" } } ``` Pour voir ce qui a changé, [récupérez le profil](https://platform.claude.com/docs/fr/api/user_profiles/retrieve) avec `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`), en utilisant `data.id`. Sa liste `enforcement_actions` affiche ses mesures ouvertes. Chaque mesure possède un `type` (`restriction` ou `ban`), un `id`, une `reason`, une heure `opened_at`, et une heure `expires_at` ou `null`. `enforcement_status` les résume : `banned` tant qu'un bannissement est ouvert, `restricted` tant qu'une autre mesure est ouverte, et `unrestricted` lorsqu'aucune ne l'est. Traitez toute autre valeur comme `restricted`. Anthropic n'envoie un événement qu'après que le profil affiche le changement ; le profil que vous récupérez affiche donc ce changement ou un changement ultérieur. Les événements peuvent arriver en retard ou dans le désordre ; utilisez donc l'état actuel du profil, et non l'ordre d'arrivée des événements. Après `user_profile.enforcement_action_resolved`, la mesure résolue ne figure plus dans la liste. Une erreur `404` signifie que le profil a été supprimé. ## Champs du point de terminaison Un point de terminaison de webhook d'organisation possède les champs suivants : | Champ | Type | Description | | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | L'ID du point de terminaison, qui commence par `wep_`. Défini par Anthropic. | | `url` | string | L'adresse à laquelle Anthropic envoie les événements. Doit être en HTTPS sur le port 443, avec un nom de domaine public, et non une adresse IP. Deux points de terminaison de webhook d'organisation activés dans votre organisation ne peuvent pas partager une URL. | | `enabled_events` | array of strings | Les [types d'événements](https://platform.claude.com/docs/fr/manage-claude/organization-webhooks#event-types) que ce point de terminaison reçoit. Une requête de création doit en lister au moins un. | | `name` | string | Un libellé facultatif pour votre propre usage. | | `description` | string | Une description facultative pour votre propre usage. | | `state` | string | `enabled` ou `disabled`. | | `disabled_reason` | string | La raison pour laquelle Anthropic a désactivé le point de terminaison. Vide sinon. | | `created_at` | string | Le moment où le point de terminaison a été créé. Défini par Anthropic. | | `updated_at` | string | Le moment où le point de terminaison a été modifié pour la dernière fois. Défini par Anthropic. | | `signing_secret` | string | Un secret préfixé par `whsec_`, créé avec le point de terminaison. Seules les réponses qui créent le point de terminaison ou remplacent le secret l'incluent ; stockez-le donc de manière sécurisée. | ```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" } ``` Une organisation peut avoir jusqu'à 32 points de terminaison de webhook d'organisation. Les points de terminaison de webhook désactivés comptent toujours dans ce total. ## Livraisons Les livraisons suivent la spécification [Standard Webhooks](https://www.standardwebhooks.com/). Chacune contient les en-têtes `webhook-id`, `webhook-timestamp` et `webhook-signature`. Avant de faire confiance à un événement, vérifiez sa signature avec le secret de signature du point de terminaison, à l'aide de n'importe quelle bibliothèque Standard Webhooks. Renvoyez n'importe quel statut `2xx` dans un délai de 5 secondes, et effectuez les traitements lents ensuite. Toute autre réponse, ou l'absence de réponse, compte comme une tentative échouée. * **Doublons :** Un point de terminaison peut recevoir le même événement plusieurs fois, avec le même `id` d'événement (la même valeur que l'en-tête `webhook-id`). Dédupliquez sur cette valeur. * **Nouvelles tentatives :** Si une livraison échoue, Anthropic la retente quelques fois au cours des minutes suivantes. Si toutes les tentatives échouent, Anthropic abandonne l'événement. Pour rattraper votre retard, listez vos profils par statut d'application, comme dans [Avant votre premier événement](https://platform.claude.com/docs/fr/manage-claude/organization-webhooks#before-your-first-event). * **Désactivation automatique :** Anthropic désactive un point de terminaison lorsque : * Il renvoie une redirection (`3xx`). * Son URL se résout en une adresse IP non publique. * Ses livraisons échouent de manière répétée. Anthropic ignore les événements destinés à un point de terminaison désactivé et ne les envoie pas ultérieurement. ## Gérer les points de terminaison Avec l'Admin API, vous pouvez effectuer les requêtes suivantes : | Tâche | Requête | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lister les points de terminaison de votre organisation | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/list) | | Créer un point de terminaison | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/create) | | Obtenir un point de terminaison | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/retrieve) | | Mettre à jour les champs `url`, `name`, `description`, `enabled_events` ou `state` d'un point de terminaison | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/update) | | Supprimer un point de terminaison | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/delete) | | Remplacer le secret de signature | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/fr/api/beta/organization/webhooks/regenerate_signing_secret) | Lors d'une mise à jour, `enabled_events` remplace l'intégralité de la liste des types d'événements du point de terminaison. Une liste vide ne vide pas la liste : le point de terminaison conserve les types d'événements qu'il avait. Pour arrêter les livraisons, envoyez `"state": "disabled"` ou supprimez le point de terminaison. Pour réactiver un point de terminaison, y compris après qu'Anthropic l'a désactivé, envoyez `"state": "enabled"` dans une requête de mise à jour. Lorsque vous remplacez le secret de signature, l'ancien secret cesse immédiatement de fonctionner. Les livraisons effectuées à partir de ce moment, y compris les nouvelles tentatives pour des événements antérieurs, sont signées avec le nouveau secret ; mettez donc à jour votre récepteur sans attendre. Envoyez l'en-tête `anthropic-beta: webhooks-2026-10-07` avec chaque requête. Le SDK et la CLI l'envoient pour vous. Cet exemple liste les points de terminaison de votre organisation, en utilisant une clé Admin API provenant 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 ``` En l'absence de points de terminaison, l'API renvoie une liste vide : ```json { "data": [], "has_more": false } ``` Une liste renvoie jusqu'à 20 points de terminaison par défaut. Définissez `limit` pour en obtenir jusqu'à 100. Si `has_more` vaut `true`, passez le `last_id` de la réponse comme `after_id` pour obtenir la page suivante. Cet exemple crée un point de terminaison qui reçoit les deux types d'événements : ```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 réponse est le nouveau point de terminaison, tel qu'illustré dans [Champs du point de terminaison](https://platform.claude.com/docs/fr/manage-claude/organization-webhooks#endpoint-fields), accompagné de son `signing_secret`. ## Erreurs Une requête renvoie une erreur `400` si : * Son `url` ne respecte pas les règles décrites dans [Champs du point de terminaison](https://platform.claude.com/docs/fr/manage-claude/organization-webhooks#endpoint-fields), ou une requête de création ne liste aucun type d'événement. Le message d'erreur indique le problème. * Votre organisation n'a pas d'espace de travail par défaut. * Les webhooks d'organisation ne sont pas disponibles pour votre organisation parce que son espace de travail par défaut utilise une [clé de chiffrement gérée par le client](https://platform.claude.com/docs/fr/manage-claude/cmek). Le message d'erreur l'indique. * Elle donnerait à votre organisation plus de 32 points de terminaison de webhook d'organisation. * Elle place dans `enabled_events` un type d'événement autre que les deux décrits dans [Types d'événements](https://platform.claude.com/docs/fr/manage-claude/organization-webhooks#event-types). Le message d'erreur liste les types acceptés. Une requête renvoie une erreur `403` si le rôle de votre compte n'inclut pas l'autorisation requise par la requête. L'erreur nomme cette autorisation. Une requête renvoie une erreur `404` si : * Elle n'envoie pas l'en-tête `anthropic-beta: webhooks-2026-10-07`. * Anthropic n'a pas activé les webhooks d'organisation pour votre organisation. * La préparation HIPAA est activée pour votre organisation. * Elle utilise un type d'identifiant que ces requêtes n'acceptent pas. * Son `webhook_endpoint_id` ne correspond à aucun point de terminaison de votre organisation. Une requête renvoie une erreur `409` si : * Elle amènerait deux points de terminaison de webhook d'organisation activés à partager une URL. * Une autre requête a modifié les points de terminaison de votre organisation au même moment. Réessayez la requête.