# Claude組織webhookの受信設計と取りこぼし対策

> Claudeの組織webhookは5秒以内の2xx返却と署名検証が必須で、再送は数分で打ち切られます。中小SaaSが取りこぼさない受信と照合ジョブの設計をまとめます。

- Canonical: https://kuucorp.com/blog/claude-org-webhook-enforcement-receiver-reconcile-smb/
- Date: 2026-11-04
- Last modified: 2026-11-04
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
自社サービスにClaudeを組み込んで顧客に提供している中小SaaSでは、顧客1社の不正利用が原因で自社全体のAPIが止まるリスクがあります。ユーザープロファイルで顧客単位に分離しても、制限やBANが発生したことに自社が気づけなければ、問い合わせ対応が後手に回ります。この記事は、Anthropicの組織webhook（ベータ）を受信して、制限・BANを検知する小さな受信基盤の作り方をまとめます。

## 組織webhookで何が通知されるのか

> 組織webhookは、ユーザープロファイルへの制限やBANの開始と終了を通知する仕組みです。イベント種別は2つだけで、通知にはIDしか含まれません。

通知されるイベントは `user_profile.enforcement_action_opened` と `user_profile.enforcement_action_resolved` の2種類です。ペイロードの `data.id` はプロファイルID（`uprof_`）、`data.enforcement_action_id` は対応ID（`enac_`）で、理由や期限は入っていません。

詳細は `GET /v1/user_profiles/{id}` で取得し、`enforcement_status`（`unrestricted` / `restricted` / `banned`）と `enforcement_actions` を読みます。ベータヘッダー `webhooks-2026-10-07` が必要で、利用には営業窓口への申請が要ります。現時点の公式ドキュメントには、イベント配信がまだ稼働しておらず、登録しても何も届かないと注記があります。受信側の実装は先に進められますが、本番の監視は後述の照合ジョブを主、webhookを補助として設計してください。

## どう署名を検証し、5秒以内に応答するか

> 配信はStandard Webhooks仕様に従い、署名検証と5秒以内の2xx返却が求められます。検証は受け取った生のバイト列で行い、処理は応答後に回します。

各配信には `webhook-id`、`webhook-timestamp`、`webhook-signature` の3ヘッダーが付きます。仕様上、署名対象は `id.timestamp.payload` を連結した文字列で、HMAC-SHA256（`v1` 接頭辞）です。JSONを再整形すると署名が合わなくなるため、パース前の生ボディで検証します。

実装の要点は次のとおりです。

1. 署名はライブラリで検証し、比較は定数時間で行う
2. 署名ヘッダーには複数の署名が並ぶことがあり、1つでも一致すれば受理する（鍵ローテーション対応）
3. `webhook-timestamp` が現在時刻から大きくずれた配信は拒否する
4. 検証後は永続キューに積んで即座に2xxを返し、プロファイル取得などの重い処理は後続のワーカーで行う
5. シークレットは `whsec_` で始まり、作成時と再生成時のレスポンスにしか含まれないため、受け取った時点で秘匿ストアに保存する

シークレットを再生成すると旧シークレットは即座に失効し、再送分も新シークレットで署名されます。受信側の更新が遅れると正規の配信を落とすので、再生成は受信側の設定変更とセットで手順化します。

## 重複・順序逆転・取りこぼしにどう備えるか

> 同じイベントが複数回届き、順序も前後し、全再送に失敗すると破棄されます。状態の正は常にプロファイルAPIの現在値に置きます。

公式ドキュメントが明示している挙動は3点です。

- 重複: 同じイベントIDで複数回届くことがある。`webhook-id` で重複排除する
- 順序: 遅延や順序逆転があり得る。到着順ではなくプロファイルの現在状態を信頼する
- 再送: 失敗した配信は数分間リトライされ、全部失敗するとイベントは破棄される

さらに、エンドポイントが自動で無効化される条件があります。3xxリダイレクトを返した場合、URLが非公開IPに解決された場合、配信失敗が続いた場合です。無効化中のイベントは、後から送られません。

したがって受信ハンドラは「通知を受けたら該当プロファイルを再取得して状態を上書きする」だけの冪等な処理にします。加えて、定期の照合ジョブを持ちます。`GET /v1/user_profiles` に `enforcement_status[]=restricted` と `enforcement_status[]=banned` を指定して一覧し、`next_page` が `null` になるまでページを辿ります。公式は、`limit` より少ない件数や空の応答がページ途中で返り得ると注記しているため、件数ではなく `next_page` で終端を判定します。また `enforcement_status` の変化は `updated_at` に反映されるとは限らないので、前回値との差分で検知します。

## 中小SaaSの最小構成はどうなるか

> 最小構成は、受信エンドポイント、キュー、照合ジョブ、通知の4点です。エンドポイントの有効状態は定期的に確認します。

- 受信: 署名検証、イベントID重複排除、キュー投入、2xx返却
- ワーカー: プロファイル再取得、自社の顧客台帳と突き合わせ、状態を保存
- 照合ジョブ: 1日数回、制限・BAN中のプロファイルを全件一覧して台帳と差分を取る。初回に既存の制限を拾う役目も兼ねる
- 通知: 自社の顧客サポートへ、顧客名・`reason`・`expires_at` を通知する。未知の `enforcement_status` は `restricted` として扱う
- 健全性確認: `GET /v1/organizations/webhooks` で `state` と `disabled_reason` を見て、無効化を検知する

制約も押さえておきます。登録できるエンドポイントは最大32件、URLはポート443のHTTPSで公開ドメイン名が必要です。組織のデフォルトワークスペースが顧客管理暗号鍵（CMEK）を使う場合、およびHIPAA対応を有効にしている場合は利用できません。登録・変更・削除と署名シークレット再生成は admin / owner / primary owner のロールに限られます。

## 参考

- [Organization webhooks — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/organization-webhooks)
- [User profiles — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/user-profiles)
- [Standard Webhooks 仕様](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)
- [Release notes — Claude Platform Docs](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

組織webhookは、顧客単位の制限・BANを自社が即座に把握するための通知です。配信が稼働していない現状では、照合ジョブを主、webhookを補助にし、署名検証・重複排除・冪等な再取得の受信側を先に用意しておくのが堅実です。顧客別の統制を含むClaude基盤の運用設計は、[Kuuの中小・成長企業向けAI導入支援](https://kuucorp.com/services/ai-ops/)までご相談ください。
