Create Webhooks

Create Webhooks

V2 webhooks can monitor specific files or folders.

This API requires the application to have the "Manage Webhooks" scope enabled.

To attach a webhook to a file, call the create webhook endpoint with the type of file, the ID of the file, a URL to send webhook notifications to, and a list of triggers.

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('Webhook ID is {0} and the address is {1}'.format(webhook.id, 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)\"")
}

To attach a webhook to an folder, call the create webhook endpoint with the type of folder, the ID of the folder, a URL to send webhook notifications to, and a list of triggers.

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('Webhook ID is {0} and the address is {1}'.format(webhook.id, 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' ] }
		*/
	});

Webhooks do cascade, so if set on a parent folder it will also watch subfolders for the selected triggers.

Ownership

It is best practice and strongly recommend to create webhooks with a Service Account, or user that will not be deleted, to avoid potential issues with webhook delivery due to loss of access to content.

Similar to files and folders, webhooks are owned by a user. If a user who owns a webhook is deleted, they will lose access to all files and folders that they previously had access to. Their webhooks will begin to fail validation, but our webhook service will continue to send events and require retries.

Webhook address

The notification URL specified in the address parameter must be a valid URL that you specify when you create a webhook. Every time one of the triggers is activated, this URL is called.

The notification URL must use standard port, 443 and should return an HTTP status in the range of 200 to 299 within 30 seconds of receiving the webhook payload.

Webhook triggers

The triggers are a list of strings that specify the events that will cause the webhook to fire. For example, if you want the webhook to be triggered when a user uploads a file, use FILE.UPLOADED.

A list of available triggers is available in this guide.