Webhook organisasi

Endpoint webhook organisasi menerima sebuah event ketika Anthropic membatasi atau memblokir salah satu profil pengguna organisasi Anda, dan ketika pembatasan atau pemblokiran tersebut berakhir. Anda mengelolanya dengan Admin API di bawah /v1/organizations/webhooks.

Setiap anggota organisasi Anda dapat menampilkan daftar endpoint webhook organisasi dan melihatnya dengan API, tetapi hanya anggota dengan peran admin, owner, atau primary owner yang dapat membuat, mengubah, atau menghapusnya, atau mengganti signing secret-nya.

Sebelum Anda memulai

Anda memerlukan hal-hal berikut:

• Organisasi di Claude API yang webhook organisasinya telah diaktifkan dan yang tidak mengaktifkan kesiapan HIPAA. Untuk meminta akses, hubungi tim akun Anthropic Anda.
• Salah satu kredensial berikut:
  • Kunci Admin API.
  • Token bearer OAuth dengan scope org:admin.
  • Kunci pribadi atau kunci akun layanan yang tidak dibatasi pada sebuah workspace.

Jenis event

Endpoint webhook organisasi menerima dua jenis event. Keduanya berkaitan dengan "enforcement action" (tindakan penegakan) pada profil pengguna. Tindakan penegakan adalah pembatasan atau pemblokiran yang diterapkan Anthropic pada pelanggan akhir yang diwakili oleh sebuah profil.

Menghapus sebuah profil akan mengakhiri tindakan-tindakan terbukanya tanpa event user_profile.enforcement_action_resolved.

Sebelum event pertama Anda

Profil Anda tidak akan memiliki field enforcement_status dan enforcement_actions sampai tindakan penegakan diaktifkan untuk organisasi Anda. Sampai saat itu, dan dalam setiap permintaan yang header anthropic-beta-nya berisi user-profiles-2026-09-04 atau nilai yang lebih lama, respons tidak menyertakan field tersebut dan filter daftar enforcement_status[] mengembalikan 400. Untuk mendapatkan field tersebut, hapus nilai itu dari permintaan Anda.

Jika sebuah tindakan penegakan dibuka sebelum Anthropic mengaktifkan tindakan penegakan dan pengiriman event untuk organisasi Anda, atau sebelum Anda mendaftarkan endpoint Anda, Anda tidak mendapatkan event user_profile.enforcement_action_opened untuknya. Tindakan tersebut tetap muncul pada profil. Untuk menemukan tindakan-tindakan ini, tampilkan daftar profil Anda dengan enforcement_status[]=restricted dan enforcement_status[]=banned. Sebuah respons mungkin mengembalikan lebih sedikit profil daripada limit, atau tidak ada sama sekali, sebelum daftar berakhir, jadi teruslah meminta halaman sampai next_page bernilai null.

Isi sebuah event

Event membawa ID, bukan tindakan atau profilnya. data.id adalah ID profil, dan data.enforcement_action_id adalah ID tindakan, yang diawali dengan 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"
  }
}

Untuk melihat apa yang berubah, ambil profil tersebut dengan client.user_profiles.retrieve(), menggunakan data.id. Daftar enforcement_actions-nya menunjukkan tindakan-tindakan terbukanya. Setiap tindakan memiliki type (restriction atau ban), id, reason, waktu opened_at, dan waktu expires_at atau null. enforcement_status merangkumnya: banned selama ada pemblokiran yang terbuka, restricted selama ada tindakan lain yang terbuka, dan unrestricted ketika tidak ada. Perlakukan nilai lain apa pun sebagai restricted.

Anthropic mengirimkan event hanya setelah profil menunjukkan perubahan tersebut, sehingga profil yang Anda ambil menunjukkan perubahan itu atau perubahan yang lebih baru. Event mungkin tiba terlambat atau tidak berurutan, jadi gunakan status profil saat ini, bukan urutan kedatangan event. Setelah user_profile.enforcement_action_resolved, tindakan yang telah diselesaikan tidak lagi ada dalam daftar. 404 berarti profil tersebut telah dihapus.

Field endpoint

Endpoint webhook organisasi memiliki field-field berikut:

{
  "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"
}

Sebuah organisasi dapat memiliki hingga 32 endpoint webhook organisasi. Endpoint webhook yang dinonaktifkan tetap dihitung dalam total ini.

Pengiriman

Pengiriman mengikuti spesifikasi Standard Webhooks. Setiap pengiriman membawa header webhook-id, webhook-timestamp, dan webhook-signature. Sebelum Anda memercayai sebuah event, verifikasi tanda tangannya dengan signing secret endpoint, menggunakan library Standard Webhooks apa pun.

Kembalikan status 2xx apa pun dalam 5 detik, dan lakukan pekerjaan yang lambat setelahnya. Respons lain apa pun, atau tidak adanya respons, dihitung sebagai percobaan yang gagal.

• Duplikat: Sebuah endpoint mungkin menerima event yang sama lebih dari sekali, dengan id event yang sama (nilai yang sama dengan header webhook-id). Lakukan deduplikasi berdasarkan nilai tersebut.

• Percobaan ulang: Jika pengiriman gagal, Anthropic mencoba ulang pengiriman tersebut beberapa kali selama beberapa menit berikutnya. Jika setiap percobaan gagal, Anthropic membuang event tersebut. Untuk mengejar ketertinggalan, tampilkan daftar profil Anda berdasarkan status penegakan, seperti di Sebelum event pertama Anda.

• Penonaktifan otomatis: Anthropic menonaktifkan sebuah endpoint ketika:

  • Endpoint mengembalikan redirect (3xx).
  • URL-nya di-resolve ke alamat IP non-publik.
  • Pengirimannya terus gagal.

  Anthropic melewati event untuk endpoint yang dinonaktifkan dan tidak mengirimkannya di kemudian hari.

Mengelola endpoint

Dengan Admin API, Anda dapat membuat permintaan-permintaan berikut:

Dalam pembaruan, enabled_events menggantikan seluruh daftar jenis event endpoint. Daftar kosong tidak mengosongkan daftar: endpoint tetap mempertahankan jenis event yang dimilikinya. Untuk menghentikan pengiriman, kirim "state": "disabled" atau hapus endpoint tersebut.

Untuk mengaktifkan kembali sebuah endpoint, termasuk setelah Anthropic menonaktifkannya, kirim "state": "enabled" dalam permintaan pembaruan.

Ketika Anda mengganti signing secret, secret lama langsung berhenti berfungsi. Pengiriman sejak saat itu, termasuk percobaan ulang event sebelumnya, ditandatangani dengan secret baru, jadi segera perbarui penerima Anda.

Kirim header anthropic-beta: webhooks-2026-10-07 dengan setiap permintaan. SDK dan CLI mengirimkannya untuk Anda. Contoh ini menampilkan daftar endpoint organisasi Anda, menggunakan kunci Admin API dari ANTHROPIC_API_KEY.

client = anthropic.Anthropic()

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

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

Tanpa endpoint, API mengembalikan daftar kosong:

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

Sebuah daftar mengembalikan hingga 20 endpoint secara default. Atur limit untuk mendapatkan hingga 100. Jika has_more bernilai true, teruskan last_id dari respons sebagai after_id untuk mendapatkan halaman berikutnya.

Contoh ini membuat endpoint yang menerima kedua jenis event:

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)

Responsnya adalah endpoint baru, seperti yang ditunjukkan di Field endpoint, ditambah signing_secret-nya.

Error

Sebuah permintaan mengembalikan 400 jika:

• url-nya tidak memenuhi aturan di Field endpoint, atau permintaan pembuatan tidak mencantumkan jenis event apa pun. Pesan error menjelaskan apa yang salah.
• Organisasi Anda tidak memiliki workspace default.
• Webhook organisasi tidak tersedia untuk organisasi Anda karena workspace default-nya menggunakan kunci enkripsi yang dikelola pelanggan. Pesan error menyatakan hal tersebut.
• Permintaan tersebut akan membuat organisasi Anda memiliki lebih dari 32 endpoint webhook organisasi.
• Permintaan tersebut memasukkan jenis event selain dua jenis di Jenis event ke dalam enabled_events. Pesan error mencantumkan jenis-jenis yang diterima.

Sebuah permintaan mengembalikan 403 jika peran akun Anda tidak mencakup izin yang dibutuhkan permintaan tersebut. Error tersebut menyebutkan nama izin itu.

Sebuah permintaan mengembalikan 404 jika:

• Permintaan tersebut tidak mengirimkan header anthropic-beta: webhooks-2026-10-07.
• Anthropic belum mengaktifkan webhook organisasi untuk organisasi Anda.
• Organisasi Anda mengaktifkan kesiapan HIPAA.
• Permintaan tersebut menggunakan jenis kredensial yang tidak diterima oleh permintaan-permintaan ini.
• webhook_endpoint_id-nya tidak cocok dengan endpoint mana pun di organisasi Anda.

Sebuah permintaan mengembalikan 409 jika:

• Permintaan tersebut akan membuat dua endpoint webhook organisasi yang diaktifkan berbagi URL yang sama.
• Permintaan lain mengubah endpoint organisasi Anda pada saat yang sama. Coba ulang permintaan tersebut.

Compatibility