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"
       ]
     }'

.NET

var webhookParams = new BoxWebhookRequest()
{
    Target = new BoxRequestEntity()
    {
        Type = BoxType.file,
        Id = "22222"
    },
    Triggers = new List<string>()
    {
        "FILE.PREVIEWED"
    },
    Address = "https://example.com/webhook"
};
BoxWebhook webhook = await client.WebhooksManager.CreateWebhookAsync(webhookParams);

Java

// Listen for preview events for a file
BoxFile file = new BoxFile(api, id);
BoxWebHook.Info webhookInfo = BoxWebHook.create(file, url, BoxWebHook.Trigger.FILE.PREVIEWED);

Python

file = client.file(file_id='12345')
webhook = client.create_webhook(file, ['FILE.PREVIEWED'], 'https://example.com')
print(f'Webhook ID is {webhook.id} and the address is {webhook.address}')

Node

// Attach a webhook that sends a notification to https://example.com/webhook when
//   file 11111 is renamed or downloaded.
client.webhooks.create(
	'11111',
	client.itemTypes.FILE,
	'https://example.com/webhook',
	[
		client.webhooks.triggerTypes.FILE.RENAMED,
		client.webhooks.triggerTypes.FILE.DOWNLOADED
	])
	.then(webhook => {
		/* webhook -> {
			id: '12345',
			type: 'webhook',
			target: { id: '11111', type: 'file' },
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: 'user@example.com' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhook',
			triggers: [ 'FILE.RENAMED', 'FILE.UPLOADED' ] }
		*/
	});

iOS

client.webhooks.create(targetType: "file", targetId: "1234", triggers: [.fileDownloaded], address: "www.testurl.com") { (result: Result<Webhook, BoxSDKError>) in
    guard case let .success(webhook) = result else {
        print("Error creating webhook")
        return
    }

    print("Created webhook \"\(webhook.id)\"")
}

フォルダにWebhookを追加するには、folderの種類、フォルダの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": "234234",
         "type": "folder"
       },
       "address": "https://example.com/webhooks",
       "triggers": [
         "FILE.UPLOADED"
       ]
     }'

.NET

var webhookParams = new BoxWebhookRequest()
{
    Target = new BoxRequestEntity()
    {
        Type = BoxType.folder,
        Id = "22222"
    },
    Triggers = new List<string>()
    {
        "FILE.UPLOADED",
        "FILE.DOWNLOADED"
    },
    Address = "https://example.com/webhook
};
BoxWebhook webhook = await client.WebhooksManager.CreateWebhookAsync(webhookParams);

Java

// Listen for file upload events in the specified folder
BoxFolder folder = new BoxFolder(api, id);
BoxWebHook.Info webhookInfo = BoxWebHook.create(folder, url, BoxWebHook.Trigger.FILE_UPLOADED);

Python

folder = client.folder(folder_id='12345')
webhook = client.create_webhook(folder, ['FILE.UPLOADED', 'FILE.PREVIEWED'], 'https://example.com')
print(f'Webhook ID is {webhook.id} and the address is {webhook.address}')

Node

// Attach a webhook that sends a notification to https://example.com/webhook when
//   files are uploaded or downloaded within folder 22222.
client.webhooks.create(
	'22222',
	client.itemTypes.FOLDER,
	'https://example.com/webhook',
	[
		client.webhooks.triggerTypes.FILE.UPLOADED,
		client.webhooks.triggerTypes.FILE.DOWNLOADED
	])
	.then(webhook => {
		/* webhook -> {
			id: '1234',
			type: 'webhook',
			target: { id: '22222', type: 'folder' },
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: 'user@example.com' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhook',
			triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] }
		*/
	});

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

関連するガイド