Source: managers/webhooks.ts

  1. /**
  2.  * @fileoverview Manager for the Box Webhooks resource
  3.  */
  5. // -----------------------------------------------------------------------------
  6. // Requirements
  7. // -----------------------------------------------------------------------------
  9. import urlPath from '../util/url-path';
  10. import crypto from 'crypto';
  11. import BoxClient from '../box-client';
  13. // -----------------------------------------------------------------------------
  14. // Typedefs
  15. // -----------------------------------------------------------------------------
  17. /**
  18.  * A webhook trigger type constant
  19.  * @typedef {string} WebhookTriggerType
  20.  */
  22. enum WebhookTriggerType {
  23. 	FILE_UPLOADED = 'FILE.UPLOADED',
  24. 	FILE_PREVIEWED = 'FILE.PREVIEWED',
  25. 	FILE_DOWNLOADED = 'FILE.DOWNLOADED',
  26. 	FILE_TRASHED = 'FILE.TRASHED',
  27. 	FILE_DELETED = 'FILE.DELETED',
  28. 	FILE_RESTORED = 'FILE.RESTORED',
  29. 	FILE_COPIED = 'FILE.COPIED',
  30. 	FILE_MOVED = 'FILE.MOVED',
  31. 	FILE_LOCKED = 'FILE.LOCKED',
  32. 	FILE_UNLOCKED = 'FILE.UNLOCKED',
  33. 	FILE_RENAMED = 'FILE.RENAMED',
  35. 	COMMENT_CREATED = 'COMMENT.CREATED',
  36. 	COMMENT_UPDATED = 'COMMENT.UPDATED',
  37. 	COMMENT_DELETED = 'COMMENT.DELETED',
  39. 	TASK_ASSIGNMENT_CREATED = 'TASK_ASSIGNMENT.CREATED',
  40. 	TASK_ASSIGNMENT_UPDATED = 'TASK_ASSIGNMENT.UPDATED',
  42. 	METADATA_INSTANCE_CREATED = 'METADATA_INSTANCE.CREATED',
  43. 	METADATA_INSTANCE_UPDATED = 'METADATA_INSTANCE.UPDATED',
  44. 	METADATA_INSTANCE_DELETED = 'METADATA_INSTANCE.DELETED',
  46. 	FOLDER_CREATED = 'FOLDER.CREATED',
  47. 	FOLDER_DOWNLOADED = 'FOLDER.DOWNLOADED',
  48. 	FOLDER_RESTORED = 'FOLDER.RESTORED',
  49. 	FOLDER_DELETED = 'FOLDER.DELETED',
  50. 	FOLDER_COPIED = 'FOLDER.COPIED',
  51. 	FOLDER_MOVED = 'FOLDER.MOVED',
  52. 	FOLDER_TRASHED = 'FOLDER.TRASHED',
  53. 	FOLDER_RENAMED = 'FOLDER.RENAMED',
  55. 	WEBHOOK_DELETED = 'WEBHOOK.DELETED',
  57. 	COLLABORATION_CREATED = 'COLLABORATION.CREATED',
  58. 	COLLABORATION_ACCEPTED = 'COLLABORATION.ACCEPTED',
  59. 	COLLABORATION_REJECTED = 'COLLABORATION.REJECTED',
  60. 	COLLABORATION_REMOVED = 'COLLABORATION.REMOVED',
  61. 	COLLABORATION_UPDATED = 'COLLABORATION.UPDATED',
  63. 	SHARED_LINK_DELETED = 'SHARED_LINK.DELETED',
  64. 	SHARED_LINK_CREATED = 'SHARED_LINK.CREATED',
  65. 	SHARED_LINK_UPDATED = 'SHARED_LINK.UPDATED',
  67. 	SIGN_REQUEST_COMPLETED = 'SIGN_REQUEST.COMPLETED',
  68. 	SIGN_REQUEST_DECLINED = 'SIGN_REQUEST.DECLINED',
  69. 	SIGN_REQUEST_EXPIRED = 'SIGN_REQUEST.EXPIRED',	
  70. }
  72. // -----------------------------------------------------------------------------
  73. // Private
  74. // -----------------------------------------------------------------------------
  76. // Base path for all webhooks endpoints
  77. const BASE_PATH = '/webhooks';
  79. // This prevents replay attacks
  80. const MAX_MESSAGE_AGE = 10 * 60; // 10 minutes
  82. /**
  83.  * Compute the message signature
  84.  * @see {@Link https://developer.box.com/en/guides/webhooks/handle/setup-signatures/}
  85.  *
  86.  * @param {string} body - The request body of the webhook message
  87.  * @param {Object} headers - The request headers of the webhook message
  88.  * @param {?string} signatureKey - The signature to verify the message with
  89.  * @returns {?string} - The message signature (or null, if it can't be computed)
  90.  * @private
  91.  */
  92. function computeSignature(
  93. 	body: string,
  94. 	headers: Record<string, any>,
  95. 	signatureKey?: string
  96. ) {
  97. 	if (!signatureKey) {
  98. 		return null;
  99. 	}
  101. 	if (headers['box-signature-version'] !== '1') {
  102. 		return null;
  103. 	}
  105. 	if (headers['box-signature-algorithm'] !== 'HmacSHA256') {
  106. 		return null;
  107. 	}
  109. 	let hmac = crypto.createHmac('sha256', signatureKey);
  110. 	hmac.update(body);
  111. 	hmac.update(headers['box-delivery-timestamp']);
  113. 	const signature = hmac.digest('base64');
  115. 	return signature;
  116. }
  118. /**
  119.  * Validate the message signature
  120.  * @see {@Link https://developer.box.com/en/guides/webhooks/handle/verify-signatures/}
  121.  *
  122.  * @param {string} body - The request body of the webhook message
  123.  * @param {Object} headers - The request headers of the webhook message
  124.  * @param {string} [primarySignatureKey] - The primary signature to verify the message with
  125.  * @param {string} [secondarySignatureKey] - The secondary signature to verify the message with
  126.  * @returns {boolean} - True or false
  127.  * @private
  128.  */
  129. function validateSignature(
  130. 	body: string,
  131. 	headers: Record<string, any>,
  132. 	primarySignatureKey?: string,
  133. 	secondarySignatureKey?: string
  134. ) {
  135. 	// Either the primary or secondary signature must match the corresponding signature from Box
  136. 	// (The use of two signatures allows the signing keys to be rotated one at a time)
  137. 	const primarySignature = computeSignature(body, headers, primarySignatureKey);
  139. 	if (
  140. 		primarySignature &&
  141. 		primarySignature === headers['box-signature-primary']
  142. 	) {
  143. 		return true;
  144. 	}
  146. 	const secondarySignature = computeSignature(
  147. 		body,
  148. 		headers,
  149. 		secondarySignatureKey
  150. 	);
  152. 	if (
  153. 		secondarySignature &&
  154. 		secondarySignature === headers['box-signature-secondary']
  155. 	) {
  156. 		return true;
  157. 	}
  159. 	return false;
  160. }
  162. /**
  163.  * Validate that the delivery timestamp is not too far in the past (to prevent replay attacks)
  164.  *
  165.  * @param {Object} headers - The request headers of the webhook message
  166.  * @param {int} maxMessageAge - The maximum message age (in seconds)
  167.  * @returns {boolean} - True or false
  168.  * @private
  169.  */
  170. function validateDeliveryTimestamp(
  171. 	headers: Record<string, any>,
  172. 	maxMessageAge: number
  173. ) {
  174. 	const deliveryTime = Date.parse(headers['box-delivery-timestamp']);
  175. 	const currentTime = Date.now();
  176. 	const messageAge = (currentTime - deliveryTime) / 1000;
  178. 	if (messageAge > maxMessageAge) {
  179. 		return false;
  180. 	}
  182. 	return true;
  183. }
  185. /**
  186.  * Stringify JSON with escaped multibyte Unicode characters to ensure computed signatures match PHP's default behavior
  187.  *
  188.  * @param {Object} body - The parsed JSON object
  189.  * @returns {string} - Stringified JSON with escaped multibyte Unicode characters
  190.  * @private
  191.  */
  192. function jsonStringifyWithEscapedUnicode(body: object) {
  193. 	return JSON.stringify(body).replace(
  194. 		/[\u007f-\uffff]/g,
  195. 		(char) => `\\u${`0000${char.charCodeAt(0).toString(16)}`.slice(-4)}`
  196. 	);
  197. }
  199. // -----------------------------------------------------------------------------
  200. // Public
  201. // -----------------------------------------------------------------------------
  203. /**
  204.  * Simple manager for interacting with all 'Webhooks' endpoints and actions.
  205.  *
  206.  * @param {BoxClient} client The Box API Client that is responsible for making calls to the API
  207.  * @constructor
  208.  */
  209. class Webhooks {
  210. 	/**
  211. 	 * Primary signature key to protect webhooks against attacks.
  212. 	 * @static
  213. 	 * @type {?string}
  214. 	 */
  215. 	static primarySignatureKey: string | null = null;
  217. 	/**
  218. 	 * Secondary signature key to protect webhooks against attacks.
  219. 	 * @static
  220. 	 * @type {?string}
  221. 	 */
  222. 	static secondarySignatureKey: string | null = null;
  224. 	/**
  225. 	 * Sets primary and secondary signatures that are used to verify the Webhooks messages
  226. 	 *
  227. 	 * @param {string} primaryKey - The primary signature to verify the message with
  228. 	 * @param {string} [secondaryKey] - The secondary signature to verify the message with
  229. 	 * @returns {void}
  230. 	 */
  231. 	static setSignatureKeys(primaryKey: string, secondaryKey?: string) {
  232. 		Webhooks.primarySignatureKey = primaryKey;
  234. 		if (typeof secondaryKey === 'string') {
  235. 			Webhooks.secondarySignatureKey = secondaryKey;
  236. 		}
  237. 	}
  239. 	/**
  240. 	 * Validate a webhook message by verifying the signature and the delivery timestamp
  241. 	 *
  242. 	 * @param {string|Object} body - The request body of the webhook message
  243. 	 * @param {Object} headers - The request headers of the webhook message
  244. 	 * @param {string} [primaryKey] - The primary signature to verify the message with. If it is sent as a parameter,
  245. 		 it overrides the static variable primarySignatureKey
  246. 	* @param {string} [secondaryKey] - The secondary signature to verify the message with. If it is sent as a parameter,
  247. 		it overrides the static variable primarySignatureKey
  248. 	* @param {int} [maxMessageAge] - The maximum message age (in seconds).  Defaults to 10 minutes
  249. 	* @returns {boolean} - True or false
  250. 	*/
  251. 	static validateMessage(
  252. 		body: string | object,
  253. 		headers: Record<string, string>,
  254. 		primaryKey?: string,
  255. 		secondaryKey?: string,
  256. 		maxMessageAge?: number
  257. 	) {
  258. 		if (!primaryKey && Webhooks.primarySignatureKey) {
  259. 			primaryKey = Webhooks.primarySignatureKey;
  260. 		}
  262. 		if (!secondaryKey && Webhooks.secondarySignatureKey) {
  263. 			secondaryKey = Webhooks.secondarySignatureKey;
  264. 		}
  266. 		if (typeof maxMessageAge !== 'number') {
  267. 			maxMessageAge = MAX_MESSAGE_AGE;
  268. 		}
  270. 		// For frameworks like Express that automatically parse JSON
  271. 		// bodies into Objects, re-stringify for signature testing
  272. 		if (typeof body === 'object') {
  273. 			// Escape forward slashes to ensure a matching signature
  274. 			body = jsonStringifyWithEscapedUnicode(body).replace(/\//g, '\\/');
  275. 		}
  277. 		if (!validateSignature(body, headers, primaryKey, secondaryKey)) {
  278. 			return false;
  279. 		}
  281. 		if (!validateDeliveryTimestamp(headers, maxMessageAge)) {
  282. 			return false;
  283. 		}
  285. 		return true;
  286. 	}
  288. 	client: BoxClient;
  290. 	triggerTypes!: Record<
  291. 		| 'FILE'
  292. 		| 'COMMENT'
  293. 		| 'TASK_ASSIGNMENT'
  294. 		| 'METADATA_INSTANCE'
  295. 		| 'FOLDER'
  296. 		| 'WEBHOOK'
  297. 		| 'COLLABORATION'
  298. 		| 'SHARED_LINK'
  299. 		| 'SIGN_REQUEST',
  300. 		Record<string, WebhookTriggerType>
  301. 	>;
  302. 	validateMessage!: typeof Webhooks.validateMessage;
  304. 	constructor(client: BoxClient) {
  305. 		// Attach the client, for making API calls
  306. 		this.client = client;
  307. 	}
  309. 	/**
  310. 	 * Create a new webhook on a given Box object, specified by type and ID.
  311. 	 *
  312. 	 * API Endpoint: '/webhooks'
  313. 	 * Method: POST
  314. 	 *
  315. 	 * @param {string} targetID - Box ID  of the item to create webhook on
  316. 	 * @param {ItemType} targetType - Type of item the webhook will be created on
  317. 	 * @param {string} notificationURL - The URL of your application where Box will notify you of events triggers
  318. 	 * @param {WebhookTriggerType[]} triggerTypes - Array of event types that trigger notification for the target
  319. 	 * @param {Function} [callback] - Passed the new webhook information if it was acquired successfully
  320. 	 * @returns {Promise<Object>} A promise resolving to the new webhook object
  321. 	 */
  322. 	create(
  323. 		targetID: string,
  324. 		targetType: string,
  325. 		notificationURL: string,
  326. 		triggerTypes: WebhookTriggerType[],
  327. 		callback?: Function
  328. 	) {
  329. 		var params = {
  330. 			body: {
  331. 				target: {
  332. 					id: targetID,
  333. 					type: targetType,
  334. 				},
  335. 				address: notificationURL,
  336. 				triggers: triggerTypes,
  337. 			},
  338. 		};
  340. 		var apiPath = urlPath(BASE_PATH);
  341. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  342. 			apiPath,
  343. 			params,
  344. 			callback
  345. 		);
  346. 	}
  348. 	/**
  349. 	 * Returns a webhook object with the specified Webhook ID
  350. 	 *
  351. 	 * API Endpoint: '/webhooks/:webhookID'
  352. 	 * Method: GET
  353. 	 *
  354. 	 * @param {string} webhookID - ID of the webhook to retrieve
  355. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  356. 	 * @param {Function} [callback] - Passed the webhook information if it was acquired successfully
  357. 	 * @returns {Promise<Object>} A promise resolving to the webhook object
  358. 	 */
  359. 	get(webhookID: string, options?: Record<string, any>, callback?: Function) {
  360. 		var params = {
  361. 			qs: options,
  362. 		};
  364. 		var apiPath = urlPath(BASE_PATH, webhookID);
  365. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  366. 			apiPath,
  367. 			params,
  368. 			callback
  369. 		);
  370. 	}
  372. 	/**
  373. 	 * Get a list of webhooks that are active for the current application and user.
  374. 	 *
  375. 	 * API Endpoint: '/webhooks'
  376. 	 * Method: GET
  377. 	 *
  378. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  379. 	 * @param {int} [options.limit=100] - The number of webhooks to return
  380. 	 * @param {string} [options.marker] - Pagination marker
  381. 	 * @param {Function} [callback] - Passed the list of webhooks if successful, error otherwise
  382. 	 * @returns {Promise<Object>} A promise resolving to the collection of webhooks
  383. 	 */
  384. 	getAll(
  385. 		options?: {
  386. 			limit?: number;
  387. 			marker?: string;
  388. 		},
  389. 		callback?: Function
  390. 	) {
  391. 		var params = {
  392. 			qs: options,
  393. 		};
  395. 		var apiPath = urlPath(BASE_PATH);
  396. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  397. 			apiPath,
  398. 			params,
  399. 			callback
  400. 		);
  401. 	}
  403. 	/**
  404. 	 * Update a webhook
  405. 	 *
  406. 	 * API Endpoint: '/webhooks/:webhookID'
  407. 	 * Method: PUT
  408. 	 *
  409. 	 * @param {string} webhookID - The ID of the webhook to be updated
  410. 	 * @param {Object} updates - Webhook fields to update
  411. 	 * @param {string} [updates.address] - The new URL used by Box to send a notification when webhook is triggered
  412. 	 * @param {WebhookTriggerType[]} [updates.triggers] - The new events that triggers a notification
  413. 	 * @param {Function} [callback] - Passed the updated webhook information if successful, error otherwise
  414. 	 * @returns {Promise<Object>} A promise resolving to the updated webhook object
  415. 	 */
  416. 	update(
  417. 		webhookID: string,
  418. 		updates?: {
  419. 			address?: string;
  420. 			triggers?: WebhookTriggerType[];
  421. 		},
  422. 		callback?: Function
  423. 	) {
  424. 		var apiPath = urlPath(BASE_PATH, webhookID),
  425. 			params = {
  426. 				body: updates,
  427. 			};
  429. 		return this.client.wrapWithDefaultHandler(this.client.put)(
  430. 			apiPath,
  431. 			params,
  432. 			callback
  433. 		);
  434. 	}
  436. 	/**
  437. 	 * Delete a specified webhook by ID
  438. 	 *
  439. 	 * API Endpoint: '/webhooks/:webhookID'
  440. 	 * Method: DELETE
  441. 	 *
  442. 	 * @param {string} webhookID - ID of webhook to be deleted
  443. 	 * @param {Function} [callback] - Empty response body passed if successful.
  444. 	 * @returns {Promise<void>} A promise resolving to nothing
  445. 	 */
  446. 	delete(webhookID: string, callback?: Function) {
  447. 		var apiPath = urlPath(BASE_PATH, webhookID);
  448. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  449. 			apiPath,
  450. 			null,
  451. 			callback
  452. 		);
  453. 	}
  454. }
  456. /**
  457.  * Enum of valid webhooks event triggers
  458.  *
  459.  * @readonly
  460.  * @enum {WebhookTriggerType}
  461.  */
  462. Webhooks.prototype.triggerTypes = {
  463. 	FILE: {
  464. 		UPLOADED: WebhookTriggerType.FILE_UPLOADED,
  465. 		PREVIEWED: WebhookTriggerType.FILE_PREVIEWED,
  466. 		DOWNLOADED: WebhookTriggerType.FILE_DOWNLOADED,
  467. 		TRASHED: WebhookTriggerType.FILE_TRASHED,
  468. 		DELETED: WebhookTriggerType.FILE_DELETED,
  469. 		RESTORED: WebhookTriggerType.FILE_RESTORED,
  470. 		COPIED: WebhookTriggerType.FILE_COPIED,
  471. 		MOVED: WebhookTriggerType.FILE_MOVED,
  472. 		LOCKED: WebhookTriggerType.FILE_LOCKED,
  473. 		UNLOCKED: WebhookTriggerType.FILE_UNLOCKED,
  474. 		RENAMED: WebhookTriggerType.FILE_RENAMED,
  475. 	},
  476. 	COMMENT: {
  477. 		CREATED: WebhookTriggerType.COMMENT_CREATED,
  478. 		UPDATED: WebhookTriggerType.COMMENT_UPDATED,
  479. 		DELETED: WebhookTriggerType.COMMENT_DELETED,
  480. 	},
  481. 	TASK_ASSIGNMENT: {
  482. 		CREATED: WebhookTriggerType.TASK_ASSIGNMENT_CREATED,
  483. 		UPDATED: WebhookTriggerType.TASK_ASSIGNMENT_UPDATED,
  484. 	},
  485. 	METADATA_INSTANCE: {
  486. 		CREATED: WebhookTriggerType.METADATA_INSTANCE_CREATED,
  487. 		UPDATED: WebhookTriggerType.METADATA_INSTANCE_UPDATED,
  488. 		DELETED: WebhookTriggerType.METADATA_INSTANCE_DELETED,
  489. 	},
  490. 	FOLDER: {
  491. 		CREATED: WebhookTriggerType.FOLDER_CREATED,
  492. 		DOWNLOADED: WebhookTriggerType.FOLDER_DOWNLOADED,
  493. 		RESTORED: WebhookTriggerType.FOLDER_RESTORED,
  494. 		DELETED: WebhookTriggerType.FOLDER_DELETED,
  495. 		COPIED: WebhookTriggerType.FOLDER_COPIED,
  496. 		MOVED: WebhookTriggerType.FOLDER_MOVED,
  497. 		TRASHED: WebhookTriggerType.FOLDER_TRASHED,
  498. 		RENAMED: WebhookTriggerType.FOLDER_RENAMED,
  499. 	},
  500. 	WEBHOOK: {
  501. 		DELETED: WebhookTriggerType.WEBHOOK_DELETED,
  502. 	},
  503. 	COLLABORATION: {
  504. 		CREATED: WebhookTriggerType.COLLABORATION_CREATED,
  505. 		ACCEPTED: WebhookTriggerType.COLLABORATION_ACCEPTED,
  506. 		REJECTED: WebhookTriggerType.COLLABORATION_REJECTED,
  507. 		REMOVED: WebhookTriggerType.COLLABORATION_REMOVED,
  508. 		UPDATED: WebhookTriggerType.COLLABORATION_UPDATED,
  509. 	},
  510. 	SHARED_LINK: {
  511. 		DELETED: WebhookTriggerType.SHARED_LINK_DELETED,
  512. 		CREATED: WebhookTriggerType.SHARED_LINK_CREATED,
  513. 		UPDATED: WebhookTriggerType.SHARED_LINK_UPDATED,
  514. 	},
  515. 	SIGN_REQUEST: {
  516. 		COMPLETED: WebhookTriggerType.SIGN_REQUEST_COMPLETED,
  517. 		DECLINED: WebhookTriggerType.SIGN_REQUEST_DECLINED,
  518. 		EXPIRED: WebhookTriggerType.SIGN_REQUEST_EXPIRED,
  519. 	}
  520. };
  522. Webhooks.prototype.validateMessage = Webhooks.validateMessage;
  524. /**
  525.  * @module box-node-sdk/lib/managers/webhooks
  526.  * @see {@Link Webhooks}
  527.  */
  528. export = Webhooks;