Webhookの作成
Webhookの作成
V2 Webhookは、特定のファイルまたはフォルダを監視でき、開発者コンソールでもAPIでも作成できます。
開発者コンソール
Webhookを作成するには、以下の手順に従います。
- 開発者コンソールで、目的のアプリケーションに移動します。
- [Webhook] タブを選択します。
- [Webhookを作成] ボタンをクリックします。
- ドロップダウンリストで [V2] を選択します。
- フォームに入力します。
- [Webhookを作成] ボタンをクリックして変更を保存します。
必須フィールド
フィールド名 | 説明 | 必須 |
---|---|---|
URLアドレス | Webhookによって通知されるURLアドレス。 | はい |
コンテンツタイプ | Webhookが構成されているコンテンツのタイプ (ファイル/フォルダ)。 | はい |
トリガー | Webhookをアクティブ化するさまざまなトリガー。 | はい |
API
ファイルにWebhookを追加するには、file
の種類、ファイルのID、Webhook通知の送信先URL、およびトリガーのリストを指定してWebhookを作成エンドポイントを呼び出します。
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"
]
}'
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);
client.webhooks.create_webhook(
CreateWebhookTarget(id=folder.id, type=CreateWebhookTargetTypeField.FOLDER),
"https://example.com/new-webhook",
[CreateWebhookTriggers.FILE_UPLOADED],
)
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)})));
// Listen for preview events for a file
BoxFile file = new BoxFile(api, id);
BoxWebHook.Info webhookInfo = BoxWebHook.create(file, url, BoxWebHook.Trigger.FILE.PREVIEWED);
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}')
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);
// 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' ] }
*/
});
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 -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"
]
}'
// 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);
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}')
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);
// 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アドレス
address
パラメータで指定する通知URLは、Webhookの作成時に指定した有効なURLである必要があります。このURLは、いずれかのトリガーがアクティブになるたびに呼び出されます。
通知URLは標準ポート443
を使用する必要があり、Webhookペイロード の受信から30秒以内に200
~299
の範囲のHTTPステータスを返す必要があります。
Webhookトリガー
トリガーのリストでは、Webhookによって発生するイベントを表す文字列を指定します。たとえば、ユーザーがファイルをアップロードしたときにWebhookをトリガーするにはFILE.UPLOADED
を使用します。
使用可能なトリガーのリストは、こちらのガイドを参照してください。