Box Webhook V1とV2の違いを整理する

BoxのWebhookにはV1とV2の2つのバージョンがあります。ドキュメントを読んでいると両方の名前が登場しますが、どちらを使えばいいのか、何が違うのかが分かりにくいと感じることがあります。この記事では、両バージョンの違いを比較表と具体例で整理します。

この記事の目的

BoxのWebhook V1とV2の違いを網羅的に整理し、「どちらを選ぶべきか」「V1を使わざるを得ないケースはどれか」を明確にする。

1. 全体像の比較

まず、2つのバージョンを横断的に比較します。

結論から言えば、特別な理由がない限りV2を使うのが正解です。V1を選ぶ理由は、ルートフォルダ（ID: 0）を監視したい場合のみです。

2. V1 Webhook

2-1. 特徴

V1はBoxが最初に提供したWebhookの仕組みです。Developer Consoleから設定するだけで使い始められる手軽さが特徴ですが、柔軟性とセキュリティの面でV2に劣ります。

監視対象が「アカウント全体」に固定されるのが最大の制約です。特定のフォルダだけを監視するといった絞り込みができません。

また、V1で作成したWebhookはAPIで一覧取得できません。Developer Consoleでしか確認できないため、プログラムから管理することが困難です。

2-2. ペイロードの形式

V1では、Developer Consoleで事前に選択した項目の値だけが送信されます。V2のように対象ファイル・フォルダの情報がフルで自動的に含まれるわけではないため、受信したい情報を設定段階で決めておく必要があります。

2-3. セキュリティ上の注意点

V1は署名検証に非対応です。受信したリクエストが本当にBoxから送られたものかを確認する手段が標準で提供されていないため、エンドポイントを公開する際のなりすましリスクへの対策を別途講じる必要があります。通信もHTTPを許可しているため、HTTPS接続を強制する制御はBox側ではなくアプリケーション側で行う必要があります。

2-4. V1が適しているケース

V2はルートフォルダ（ID: 0）に直接Webhookを作成できません。V2はカスケードするため、直下の子フォルダ群にそれぞれV2を設定することで実質的に同等のカバレッジは得られます。ただし、新しいフォルダが作成されるたびに追加設定が必要になります。

アカウント全体を1つの設定で一括監視したい場合は、V1が適しています。

参考：V1 Webhooks – Box Developer Documentation

3. V2 Webhook

3-1. 特徴

V2はBoxが推奨する現行のWebhookです。特定のファイルやフォルダに紐付けて作成でき、イベントの種類、セキュリティ、信頼性のすべてでV1を上回ります。

3-2. 作成方法

Developer ConsoleのほかにAPIからも作成できます。これにより、アプリケーションのデプロイ時やフォルダ作成と連動してWebhookをプログラムで登録・管理することが可能です。

参考：Create V2 Webhooks – Box Developer Documentation

3-3. ペイロード

V2のペイロードはHTTPヘッダーとJSONボディで構成されます。

ヘッダー

ボディ（例）

{
  "type": "webhook_event",
  "id": "unique-event-id",
  "created_at": "2026-09-28T10:00:00Z",
  "trigger": "FILE.UPLOADED",
  "webhook": { "id": "123", "type": "webhook" },
  "created_by": {
    "type": "user",
    "id": "9876",
    "name": "Alice",
    "login": "alice@example.com"
  },
  "source": {
    "type": "file",
    "id": "555",
    "name": "report.pdf",
    "parent": { "type": "folder", "id": "111" }
  }
}

source にはイベント対象のファイル・フォルダの情報がフルオブジェクトで含まれます。V1のようにパラメータを事前に選択する必要はありません。

参考：V2 Webhooks Payload – Box Developer Documentation

3-4. 署名検証

V2の最大のセキュリティ機能がペイロード署名です。Boxはリクエスト本文とタイムスタンプをプライマリキーとセカンダリキーでそれぞれ独立してHMAC-SHA256署名し、2つの署名をヘッダーに付与して送信します。受信側は次の手順で正当性を検証します。

最初に BOX-DELIVERY-TIMESTAMP が現在時刻から10分以内かを確認することが推奨されます。これにより、過去の正規リクエストを再送する「リプレイ攻撃」を防ぐことができます。タイムスタンプが有効であれば、本文とタイムスタンプを同じキーでHMAC-SHA256計算し直し、ヘッダーの署名と一致するかを検証します。

キーローテーションに対応するためにプライマリ・セカンダリの2キー体制になっています。片方のキーで検証が通れば正規リクエストとして扱います。

参考：Verify Box Webhook Signatures

3-5. 自動再試行

受信エンドポイントが30秒以内に 200〜299 のHTTPステータスコードを返さなかった場合、BoxはWebhookを最大5回自動で再試行します（1時間以内）。再試行のたびに BOX-DELIVERY-ID が変わるため、id（ボディのイベントID、再試行でも変わらない）で冪等性を担保した処理を実装することが推奨されます。

3-6. V2の制限事項

参考：V2 Webhook Limitations – Box Developer Documentation

4. まとめ

BoxのWebhookはV2を使うのが基本方針です。署名検証・自動再試行・API管理・豊富なイベントトリガーなど、実運用に必要な機能がV2に集約されています。

V1が適している場面は「アカウント全体を1つの設定で一括監視したい」場合です。V2はルートフォルダ（ID: 0）への直接設定はできませんが、子フォルダへの設定とカスケード動作を組み合わせることで同等のカバレッジを得ることができます。

参考リンク

• Webhooks overview – Box Developer Documentation
• V1 Webhooks – Box Developer Documentation
• V2 Webhooks – Box Developer Documentation
• V2 Webhook Limitations – Box Developer Documentation
• Verify Box Webhook Signatures
• V2 Webhooks Enhancements – Box Support