Skip to content

Latest commit

 

History

History
214 lines (187 loc) · 6.51 KB

webhooks.md

File metadata and controls

214 lines (187 loc) · 6.51 KB
Raw

Webhooks

A webhook object enables you to attach events triggers to Box files and folders. These event triggers monitor events on Box objects and notify your application, via HTTP requests to a URL of your choosing, when they occur.

Create a Webhook

To attach a webhook to an item, call the webhooks.create(fileID, targetType, notificationURL, triggerTypes, callback) method with the type and ID of the item, a URL to send notifications to, and a list of triggers.

The notification URL must be a valid HTTPS URL that you specify when you create a webhook.

The triggerTypes param is an array of strings. Available options are documented here: https://developer.box.com/guides/webhooks/triggers/

// 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: '[email protected]' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhook',
			triggers: [ 'FILE.RENAMED', 'FILE.UPLOADED' ] }
		*/
	});
// 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: '[email protected]' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhook',
			triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] }
		*/
	});

Get a Webhook's Information

Retrieve information about a specific webhook by calling webhooks.get(webhookID, options, callback) to retrieve a webhook by ID.

client.webhooks.get('1234')
	.then(webhook => {
		/* webhook -> {
			id: '1234',
			type: 'webhook',
			target: { id: '22222', type: 'folder' },
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhook',
			triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] }
		*/
	});

Get all Webhooks Information

Get a list of all webhooks for the requesting application and user by calling the webhooks.getAll(options, callback) method. The maximum limit per page of results is 200, Box uses the default limit of 100.

client.webhooks.getAll()
	.then(webhooks => {
		/* webhooks -> {
			next_marker: 'ZmlQZS0xLTE%3D',
			entries: 
			[ { id: '1234',
				type: 'webhook',
				target: { id: '22222', type: 'folder' } },
				{ id: '5678',
				type: 'webhook',
				target: { id: '11111', type: 'file' } } ],
			limit: 2 }
		*/
	});

Update a Webhook

Update a file or folder's webhook by calling webhooks.update(webhookID, updates, callback) with the field you want to update as updates.address or updates.trigger.

client.webhooks.update('678901', {address: "https://example.com/webhooks/fileActions"})
	.then(webhook => {
		/* webhook -> {
			id: '1234',
			type: 'webhook',
			target: { id: '22222', type: 'folder' },
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2016-05-09T17:41:27-07:00',
			address: 'https://example.com/webhooks/fileActions',
			triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] }
		*/
	});

Delete a Webhook

A file or folder's webhook can be removed by calling webhooks.delete(webhookID, callback).

client.webhooks.delete('1234')
	.then(() => {
		// deletion succeeded — no value returned
	});

Validate a Webhook Message

When you receive a webhook message from Box, you should validate it by calling BoxSDK.validateWebhookMessage(body, headers, primarySignatureKey, secondarySignatureKey, maxMessageAge), also available as webhooks.validateMessage(body, headers, primarySignatureKey, secondarySignatureKey, maxMessageAge).

const BoxSDK = require('box-node-sdk');
let body = '{"type":"webhook_event","webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}',
	headers = {
		'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f',
		'box-delivery-timestamp': '2020-01-01T00:00:00-07:00',
		'box-signature-algorithm': 'HmacSHA256',
		'box-signature-primary': '6TfeAW3A1PASkgboxxA5yqHNKOwFyMWuEXny/FPD5hI=',
		'box-signature-secondary': 'v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo=',
		'box-signature-version': '1'
	},
	primaryKey = 'SamplePrimaryKey',
	secondaryKey = 'SampleSecondaryKey';

let isValid = BoxSDK.validateWebhookMessage(body, headers, primaryKey, secondaryKey);
if (isValid) {
	// message is valid, accept
} else {
	// message is NOT valid, reject
}