Webhookの作成

V2 Webhookは、特定のファイルまたはフォルダを監視でき、開発者コンソールでもAPIでも作成できます。

V2 Webhookを作成できるのは、[Webhookを管理する] というスコープが選択され、アプリケーションが承認されている場合のみです。必須のアクセススコープと承認の詳細を参照してください。

Webhookを作成するには、以下の手順に従います。

開発者コンソールで、目的のアプリケーションに移動します。
[Webhook] タブを選択します。
[Webhookを作成] ボタンをクリックします。
ドロップダウンリストで [V2] を選択します。
フォームに入力します。
[Webhookを作成] ボタンをクリックして変更を保存します。

フィールド名	説明	必須
URLアドレス	Webhookによって通知されるURLアドレス。	はい
コンテンツタイプ	Webhookが構成されているコンテンツのタイプ (ファイル/フォルダ)。	はい
トリガー	Webhookをアクティブ化するさまざまなトリガー。	はい

このAPIを使用するには、アプリケーションの [Webhookを管理する] スコープが有効になっている必要があります。

ファイルにWebhookを追加するには、fileの種類、ファイルのID、Webhook通知の送信先URL、およびトリガーのリストを指定してWebhookを作成エンドポイントを呼び出します。

cURL

curl -i -X POST "https://api.box.com/2.0/webhooks" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "target": {
         "id": "21322",
         "type": "file"
       },
       "address": "https://example.com/webhooks",
       "triggers": [
         "FILE.PREVIEWED"
       ]
     }'

Node/TypeScript v10

await client.webhooks.createWebhook({
  target: {
    id: folder.id,
    type: 'folder' as CreateWebhookRequestBodyTargetTypeField,
  } satisfies CreateWebhookRequestBodyTargetField,
  address: 'https://example.com/new-webhook',
  triggers: ['FILE.UPLOADED' as CreateWebhookRequestBodyTriggersField],
} satisfies CreateWebhookRequestBody);

Python v10

client.webhooks.create_webhook(
    CreateWebhookTarget(id=folder.id, type=CreateWebhookTargetTypeField.FOLDER),
    "https://example.com/new-webhook",
    [CreateWebhookTriggers.FILE_UPLOADED],
)

.NET v10

await client.Webhooks.CreateWebhookAsync(requestBody: new CreateWebhookRequestBody(target: new CreateWebhookRequestBodyTargetField() { Id = folder.Id, Type = CreateWebhookRequestBodyTargetTypeField.Folder }, address: "https://example.com/new-webhook", triggers: Array.AsReadOnly(new [] {new StringEnum<CreateWebhookRequestBodyTriggersField>(CreateWebhookRequestBodyTriggersField.FileUploaded)})));

Swift v10

try await client.webhooks.createWebhook(requestBody: CreateWebhookRequestBody(target: CreateWebhookRequestBodyTargetField(id: folder.id, type: CreateWebhookRequestBodyTargetTypeField.folder), address: "https://example.com/new-webhook", triggers: [CreateWebhookRequestBodyTriggersField.fileUploaded]))

Java v10

client.getWebhooks().createWebhook(new CreateWebhookRequestBody(new CreateWebhookRequestBodyTargetField.Builder().id(folder.getId()).type(CreateWebhookRequestBodyTargetTypeField.FOLDER).build(), "https://example.com/new-webhook", Arrays.asList(CreateWebhookRequestBodyTriggersField.FILE_UPLOADED)))

.NET v6

await client.Webhooks.CreateWebhookAsync(requestBody: new CreateWebhookRequestBody(target: new CreateWebhookRequestBodyTargetField() { Id = folder.Id, Type = CreateWebhookRequestBodyTargetTypeField.Folder }, address: "https://example.com/new-webhook", triggers: Array.AsReadOnly(new [] {new StringEnum<CreateWebhookRequestBodyTriggersField>(CreateWebhookRequestBodyTriggersField.FileUploaded)})));

Node v4

await client.webhooks.createWebhook({
  target: {
    id: folder.id,
    type: 'folder' as CreateWebhookRequestBodyTargetTypeField,
  } satisfies CreateWebhookRequestBodyTargetField,
  address: 'https://example.com/new-webhook',
  triggers: ['FILE.UPLOADED' as CreateWebhookRequestBodyTriggersField],
} satisfies CreateWebhookRequestBody);

フォルダにWebhookを追加するには、folderの種類、フォルダのID、Webhook通知の送信先URL、およびトリガーのリストを指定してWebhookを作成エンドポイントを呼び出します。

Webhookはカスケードで適用されるため、Webhookを親フォルダに設定すると、サブフォルダでも選択されたトリガーが監視されます。

コンテンツにアクセスできなくなることでWebhookの配信に生じる可能性のある問題を回避するために、サービスアカウント (つまり削除されることのないユーザー) を使用してWebhookを作成することを強くお勧めします。

ファイルやフォルダと同様、Webhookを所有するのはユーザーです。Webhookを所有するユーザーが削除されると、以前アクセスできていたすべてのファイルとフォルダにアクセスできなくなります。ユーザーのWebhookでは検証が失敗するようになりますが、Webhookサービスは引き続きイベントを送信し、再試行を要求します。

addressパラメータで指定する通知URLは、Webhookの作成時に指定した有効なURLである必要があります。このURLは、いずれかのトリガーがアクティブになるたびに呼び出されます。

通知URLは標準ポート443を使用する必要があり、Webhookペイロードの受信から30秒以内に200～299の範囲のHTTPステータスを返す必要があります。

トリガーのリストでは、Webhookによって発生するイベントを表す文字列を指定します。たとえば、ユーザーがファイルをアップロードしたときにWebhookをトリガーするにはFILE.UPLOADEDを使用します。

使用可能なトリガーのリストは、こちらのガイドを参照してください。

Webhookの作成

Webhookの作成

開発者コンソール

必須フィールド

API

所有権

Webhookアドレス

Webhookトリガー

関連するAPI

関連するガイド