Create webhook

post
https://api.box.com/2.0
/webhooks

Creates a webhook.

Request

application/json

Request Body

stringin bodyrequired
https://example.com/webhooks

The URL that is notified by this webhook

objectin body

The item that will trigger the webhook

stringin bodyoptional
1231232

The ID of the item to trigger a webhook

stringin bodyoptional
file

The type of item to trigger a webhook

Value is one of "file", "folder"

string arrayin bodyrequired
["FILE.UPLOADED"]

An array of event names that this webhook is to be triggered for

Value is any of "FILE.UPLOADED", "FILE.PREVIEWED", "FILE.DOWNLOADED", "FILE.TRASHED", "FILE.DELETED", "FILE.RESTORED", "FILE.COPIED", "FILE.MOVED", "FILE.LOCKED", "FILE.UNLOCKED", "FILE.RENAMED", "COMMENT.CREATED", "COMMENT.UPDATED", "COMMENT.DELETED", "TASK_ASSIGNMENT.CREATED", "TASK_ASSIGNMENT.UPDATED", "METADATA_INSTANCE.CREATED", "METADATA_INSTANCE.UPDATED", "METADATA_INSTANCE.DELETED", "FOLDER.CREATED", "FOLDER.RENAMED", "FOLDER.DOWNLOADED", "FOLDER.RESTORED", "FOLDER.DELETED", "FOLDER.COPIED", "FOLDER.MOVED", "FOLDER.TRASHED", "WEBHOOK.DELETED", "COLLABORATION.CREATED", "COLLABORATION.ACCEPTED", "COLLABORATION.REJECTED", "COLLABORATION.REMOVED", "COLLABORATION.UPDATED", "SHARED_LINK.DELETED", "SHARED_LINK.CREATED", "SHARED_LINK.UPDATED"

Response

application/jsonWebhook

Returns the new webhook object.

application/jsonClient Error

Returns an error if the parameters were incorrect.

application/jsonClient Error

Returns an error if the application does not have the permission to manage webhooks.

application/jsonClient Error

Returns an error if the target item could not be found

application/jsonClient Error

Returns an error if the a webhook for this combination of target, application, and user already exists.

You can now try out some of our APIs live, right here in the documentation.
Log In

Request Example

cURL
curl -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' ] }
		*/
	});

Response Example

{
  "id": 11446498,
  "type": "webhook",
  "target": {
    "id": 1231232,
    "type": "file"
  },
  "created_by": {
    "id": 11446498,
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "address": "https://example.com/webhooks",
  "triggers": [
    "FILE.UPLOADED"
  ]
}