--- title: Organisations-Webhooks url: https://platform.claude.com/docs/de/manage-claude/organization-webhooks description: Registriere Webhook-Endpunkte für Events zu Durchsetzungsmaßnahmen gegen die Benutzerprofile deiner Organisation. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- Ein Organisations-Webhook-Endpunkt empfängt ein Event, wenn Anthropic eines der [Benutzerprofile](https://platform.claude.com/docs/de/manage-claude/user-profiles) deiner Organisation einschränkt oder sperrt und wenn die Einschränkung oder Sperre endet. Du verwaltest ihn mit der Admin API unter `/v1/organizations/webhooks`. Die Event-Zustellung ist nicht live: Anthropic sendet die beiden Events nicht, daher empfängt ein von dir registrierter Endpunkt nichts. Du kannst Endpunkte registrieren und deinen Handler anhand des Event-Formats auf dieser Seite erstellen. Jedes Mitglied deiner Organisation kann Organisations-Webhook-Endpunkte mit der API auflisten und ansehen, aber nur Mitglieder mit der Rolle Admin, Owner oder Primary Owner können sie erstellen, ändern oder löschen oder ihr Signatur-Secret ersetzen. ## Bevor du beginnst Du benötigst Folgendes: * Eine Organisation auf der Claude API, bei der Organisations-Webhooks aktiviert sind und bei der [HIPAA-Bereitschaft](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention#hipaa-readiness) nicht aktiviert ist. Um Zugang anzufordern, kontaktiere dein Anthropic-Account-Team. * Eine dieser Arten von Anmeldedaten: * Einen [Admin-API-Key](https://platform.claude.com/docs/de/manage-claude/admin-api-keys). * Ein [OAuth-Bearer-Token](https://platform.claude.com/docs/de/manage-claude/admin-api#oauth-bearer-token) mit dem Scope `org:admin`. * Einen [persönlichen oder Service-Account-Key](https://platform.claude.com/docs/de/manage-claude/authentication#key-types), der nicht auf einen Workspace beschränkt ist. ## Event-Typen Organisations-Webhook-Endpunkte akzeptieren zwei Event-Typen. Beide betreffen „enforcement actions" (Durchsetzungsmaßnahmen) gegen Benutzerprofile. Eine Durchsetzungsmaßnahme ist eine Einschränkung oder Sperre, die Anthropic gegen den Endkunden verhängt, den ein Profil repräsentiert. | Event | Auslöser | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | `user_profile.enforcement_action_opened` | Anthropic leitet eine Durchsetzungsmaßnahme gegen ein Benutzerprofil ein. | | `user_profile.enforcement_action_resolved` | Eine Durchsetzungsmaßnahme endet. Anthropic hebt sie auf, oder ihr `expires_at`-Zeitpunkt verstreicht. | Das Löschen eines Profils beendet seine offenen Maßnahmen ohne ein `user_profile.enforcement_action_resolved`-Event. ### Vor deinem ersten Event Deine Profile haben die Felder `enforcement_status` und `enforcement_actions` erst, wenn Durchsetzungsmaßnahmen für deine Organisation aktiviert sind. Bis dahin, und bei jeder Anfrage, deren `anthropic-beta`-Header `user-profiles-2026-09-04` oder einen früheren Wert enthält, lassen die Antworten die Felder weg, und der Listenfilter `enforcement_status[]` gibt einen `400` zurück. Um die Felder zu erhalten, entferne diesen Wert aus deinen Anfragen. Wenn eine Durchsetzungsmaßnahme eingeleitet wurde, bevor Anthropic Durchsetzungsmaßnahmen und die Event-Zustellung für deine Organisation aktiviert hat oder bevor du deinen Endpunkt registriert hast, erhältst du dafür kein `user_profile.enforcement_action_opened`-Event. Die Maßnahme erscheint trotzdem im Profil. Um diese Maßnahmen zu finden, [liste deine Profile auf](https://platform.claude.com/docs/de/api/user_profiles/list) mit `enforcement_status[]=restricted` und `enforcement_status[]=banned`. Eine Antwort kann weniger Profile als `limit` oder gar keine zurückgeben, bevor die Liste endet, also fordere weiter Seiten an, bis `next_page` `null` ist. ### Was ein Event enthält Events enthalten IDs, nicht die Maßnahme oder das Profil. `data.id` ist die ID des Profils, und `data.enforcement_action_id` ist die ID der Maßnahme, die mit `enac_` beginnt: ```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" } } ``` Um zu sehen, was sich geändert hat, [rufe das Profil ab](https://platform.claude.com/docs/de/api/user_profiles/retrieve) mit `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`) und verwende dabei `data.id`. Seine Liste `enforcement_actions` zeigt seine offenen Maßnahmen. Jede Maßnahme hat einen `type` (`restriction` oder `ban`), eine `id`, einen `reason`, einen `opened_at`-Zeitpunkt und einen `expires_at`-Zeitpunkt oder `null`. `enforcement_status` fasst sie zusammen: `banned`, solange eine Sperre offen ist, `restricted`, solange eine andere Maßnahme offen ist, und `unrestricted`, wenn keine offen ist. Behandle jeden anderen Wert als `restricted`. Anthropic sendet ein Event erst, wenn das Profil die Änderung zeigt, daher zeigt das abgerufene Profil diese Änderung oder eine spätere. Events können verspätet oder in falscher Reihenfolge ankommen, also verwende den aktuellen Zustand des Profils, nicht die Reihenfolge, in der Events ankommen. Nach `user_profile.enforcement_action_resolved` ist die abgeschlossene Maßnahme nicht mehr in der Liste. Ein `404` bedeutet, dass das Profil gelöscht wurde. ## Endpunkt-Felder Ein Organisations-Webhook-Endpunkt hat diese Felder: | Feld | Typ | Beschreibung | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Die ID des Endpunkts, die mit `wep_` beginnt. Von Anthropic festgelegt. | | `url` | string | Wohin Anthropic Events sendet. Muss HTTPS auf Port 443 sein, mit einem öffentlichen Domainnamen, nicht einer IP-Adresse. Zwei aktivierte Organisations-Webhook-Endpunkte in deiner Organisation können nicht dieselbe URL verwenden. | | `enabled_events` | array of strings | Die [Event-Typen](https://platform.claude.com/docs/de/manage-claude/organization-webhooks#event-types), die dieser Endpunkt empfängt. Eine Erstellungsanfrage muss mindestens einen auflisten. | | `name` | string | Eine optionale Bezeichnung für deinen eigenen Gebrauch. | | `description` | string | Eine optionale Beschreibung für deinen eigenen Gebrauch. | | `state` | string | `enabled` oder `disabled`. | | `disabled_reason` | string | Warum Anthropic den Endpunkt deaktiviert hat. Andernfalls leer. | | `created_at` | string | Wann der Endpunkt erstellt wurde. Von Anthropic festgelegt. | | `updated_at` | string | Wann sich der Endpunkt zuletzt geändert hat. Von Anthropic festgelegt. | | `signing_secret` | string | Ein „signing secret" (Signatur-Secret) mit dem Präfix `whsec_`, das mit dem Endpunkt erstellt wird. Nur die Antworten, die den Endpunkt erstellen oder das Secret ersetzen, enthalten es, also speichere es sicher. | ```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" } ``` Eine Organisation kann bis zu 32 Organisations-Webhook-Endpunkte haben. Deaktivierte Webhook-Endpunkte zählen weiterhin zu dieser Gesamtzahl. ## Zustellungen Zustellungen folgen der Spezifikation [Standard Webhooks](https://www.standardwebhooks.com/). Jede enthält die Header `webhook-id`, `webhook-timestamp` und `webhook-signature`. Bevor du einem Event vertraust, verifiziere seine Signatur mit dem Signatur-Secret des Endpunkts, mit einer beliebigen Standard-Webhooks-Bibliothek. Gib innerhalb von 5 Sekunden einen beliebigen `2xx`-Status zurück und erledige zeitaufwendige Arbeit danach. Jede andere Antwort oder keine Antwort zählt als fehlgeschlagener Versuch. * **Duplikate:** Ein Endpunkt kann dasselbe Event mehr als einmal empfangen, mit derselben Event-`id` (demselben Wert wie der `webhook-id`-Header). Dedupliziere anhand dieser ID. * **Wiederholungsversuche:** Wenn eine Zustellung fehlschlägt, wiederholt Anthropic sie einige Male in den nächsten Minuten. Wenn jeder Versuch fehlschlägt, verwirft Anthropic das Event. Um aufzuholen, liste deine Profile nach Durchsetzungsstatus auf, wie in [Vor deinem ersten Event](https://platform.claude.com/docs/de/manage-claude/organization-webhooks#before-your-first-event) beschrieben. * **Automatische Deaktivierung:** Anthropic deaktiviert einen Endpunkt, wenn: * Er eine Weiterleitung (`3xx`) zurückgibt. * Seine URL zu einer nicht öffentlichen IP-Adresse aufgelöst wird. * Seine Zustellungen wiederholt fehlschlagen. Anthropic überspringt Events für einen deaktivierten Endpunkt und sendet sie auch später nicht. ## Endpunkte verwalten Mit der Admin API kannst du diese Anfragen stellen: | Aufgabe | Anfrage | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Die Endpunkte deiner Organisation auflisten | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/list) | | Einen Endpunkt erstellen | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/create) | | Einen Endpunkt abrufen | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/retrieve) | | `url`, `name`, `description`, `enabled_events` oder `state` eines Endpunkts aktualisieren | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/update) | | Einen Endpunkt löschen | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/delete) | | Das Signatur-Secret ersetzen | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/de/api/beta/organization/webhooks/regenerate_signing_secret) | Bei einer Aktualisierung ersetzt `enabled_events` die gesamte Liste der Event-Typen des Endpunkts. Eine leere Liste leert die Liste nicht: Der Endpunkt behält die Event-Typen, die er hatte. Um Zustellungen zu stoppen, sende `"state": "disabled"` oder lösche den Endpunkt. Um einen Endpunkt wieder zu aktivieren, auch nachdem Anthropic ihn deaktiviert hat, sende `"state": "enabled"` in einer Aktualisierungsanfrage. Wenn du das Signatur-Secret ersetzt, funktioniert das alte Secret sofort nicht mehr. Zustellungen ab diesem Zeitpunkt, einschließlich der Wiederholungsversuche für frühere Events, werden mit dem neuen Secret signiert, also aktualisiere deinen Empfänger sofort. Sende den Header `anthropic-beta: webhooks-2026-10-07` mit jeder Anfrage. Das SDK und die CLI senden ihn für dich. Dieses Beispiel listet die Endpunkte deiner Organisation auf und verwendet dabei einen Admin-API-Key aus `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 ``` Ohne Endpunkte gibt die API eine leere Liste zurück: ```json { "data": [], "has_more": false } ``` Eine Liste gibt standardmäßig bis zu 20 Endpunkte zurück. Setze `limit`, um bis zu 100 zu erhalten. Wenn `has_more` `true` ist, übergib die `last_id` der Antwort als `after_id`, um die nächste Seite zu erhalten. Dieses Beispiel erstellt einen Endpunkt, der beide Event-Typen empfängt: ```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 ``` Die Antwort ist der neue Endpunkt, wie in [Endpunkt-Felder](https://platform.claude.com/docs/de/manage-claude/organization-webhooks#endpoint-fields) gezeigt, plus sein `signing_secret`. ## Fehler Eine Anfrage gibt einen `400` zurück, wenn: * Ihre `url` die Regeln in [Endpunkt-Felder](https://platform.claude.com/docs/de/manage-claude/organization-webhooks#endpoint-fields) nicht erfüllt oder eine Erstellungsanfrage keine Event-Typen auflistet. Die Fehlermeldung gibt an, was falsch ist. * Deine Organisation keinen Standard-Workspace hat. * Organisations-Webhooks für deine Organisation nicht verfügbar sind, weil ihr Standard-Workspace einen [kundenverwalteten Verschlüsselungsschlüssel](https://platform.claude.com/docs/de/manage-claude/cmek) verwendet. Die Fehlermeldung weist darauf hin. * Sie deiner Organisation mehr als 32 Organisations-Webhook-Endpunkte geben würde. * Sie einen anderen Event-Typ als die beiden in [Event-Typen](https://platform.claude.com/docs/de/manage-claude/organization-webhooks#event-types) in `enabled_events` angibt. Die Fehlermeldung listet die akzeptierten Typen auf. Eine Anfrage gibt einen `403` zurück, wenn die Rolle deines Kontos nicht die Berechtigung enthält, die die Anfrage benötigt. Der Fehler nennt diese Berechtigung. Eine Anfrage gibt einen `404` zurück, wenn: * Sie den Header `anthropic-beta: webhooks-2026-10-07` nicht sendet. * Anthropic Organisations-Webhooks für deine Organisation nicht aktiviert hat. * Deine Organisation HIPAA-Bereitschaft aktiviert hat. * Sie eine Art von Anmeldedaten verwendet, die diese Anfragen nicht akzeptieren. * Ihre `webhook_endpoint_id` keinem Endpunkt in deiner Organisation entspricht. Eine Anfrage gibt einen `409` zurück, wenn: * Sie dazu führen würde, dass zwei aktivierte Organisations-Webhook-Endpunkte dieselbe URL verwenden. * Eine andere Anfrage gleichzeitig die Endpunkte deiner Organisation geändert hat. Wiederhole die Anfrage.