約 4 分で読めます

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

自社サービスに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 のロールに限られます。

参考

まとめ

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

関連記事

Managed Agentsのwebhook設計と配信保証Python SDKのhttpx2移行でトレースが消える問題Claude 128MB化で見直すLLMゲートウェイの上限設計Claude API 2026-10-21移行のゲートウェイ設計