Work with Webhooks

This guide will take you through common tasks when working with webhooks for files and folders in Box.

These samples assume that you have obtained a valid Box client object by following the Authenticate with JWT or Authenticate with OAuth 2 guides.

Please ensure you have the "manage webhooks" application scope enabled in the configuration tab of the dev console for your application or you will receive a 403 error.

Webhooks Ruby

The Ruby SDK does not currently have methods defined for working with webhooks. When working in Ruby it will be necessary to make a direct authenticated HTTPS requests to the webhook endpoints, as shown in the samples below.

Create a Webhook

When creating a webhook, you'll listen for specific events that occur with a file or folder within a given account.

List of Webhook Event Triggers

See the event trigger list for a complete list of event triggers that you can listen for on files and folders.

To create a webhook on a file, start by defining the ID of the file and the URL that the webhook should send an HTTP POST request to once that webhook is triggered. notificationURL should be an endpoint that you control and can monitor event traffic at.

Create a new webhook on the file by calling the webhook create method, passing in the file information or object, and the webhook event(s) that you intent to listen for.

// CREATE WEBHOOK
const fileId = 'ID OF FILE TO ADD WEBHOOK TO';
const notificationURL = 'https://www.YOURSITE.com/NOTIFICATION';

client.webhooks.create(
  fileId,
  client.itemTypes.FILE,
  notificationURL,
  [
    client.webhooks.triggerTypes.FILE.DOWNLOADED
  ],
  callback
);

// Callback function
function callback(err, res) {
  // HANDLE ERROR CASE AND RESPONSE
}
import java.net.URL;
import com.box.sdk.BoxFile;
import com.box.sdk.BoxWebHook;

String fileId = "ID OF FILE TO ADD WEBHOOK TO";
URL notificationURL = new URL("https://www.YOURSITE.com/NOTIFICATION");
        		
BoxFile file = new BoxFile(client, fileId);
BoxWebHook.Info webhookInfo = BoxWebHook.create(file, notificationURL, BoxWebHook.Trigger.FILE_DOWNLOADED);
        		
// WEBHOOK ID AVAILABLE IN webhookInfo.getID()
const string fileId = "ID OF FILE TO ADD WEBHOOK TO";
const string trigger = "FILE.DOWNLOADED";
const string address = "https://www.YOURSITE.com/NOTIFICATION";

BoxRequestEntity target = new BoxRequestEntity() { Id = fileId, Type = BoxType.file };

var triggers = new List<string>() { trigger };

BoxWebhookRequest whr = new BoxWebhookRequest() { Target = target, Address = address, Triggers = triggers };

var webhook = await client.WebhooksManager.CreateWebhookAsync(whr);

// WEBHOOK ID AVAILABLE IN webhook.Id
# Define file resource and notification data
file_id = 'ID OF FILE TO ADD WEBHOOK TO'
resource = client.file(file_id=file_id)
notification_url = 'https://www.YOURSITE.com/NOTIFICATION'

# Make request to create new webhook
webhook = client.create_webhook(resource, ['FILE.DOWNLOADED'], notification_url)
# Define file and notification data
file_id = 'ID OF FILE TO ADD WEBHOOK TO';
notification_url = 'https://www.YOURSITE.com/NOTIFICATION';

# Define https request info
headers = {'Authorization': 'Bearer ' + client.access_token}
uri = URI.parse('https://api.box.com/2.0/webhooks')

# Define webhook fields
data = '{"target": {"id": "' + file_id + '", "type": "file"}, "address": "' + notification_url + '", "triggers": ["FILE.DOWNLOADED"]}'

# Make request to create new webhook
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
resp = https.post(uri.request_uri, data, headers)
json = JSON.parse(resp.body.to_json)
box webhooks create $file_id file FILE.DOWNLOADED https://www.YOURSITE.com/NOTIFICATION

Creating Webhooks for Folders

To create a webhook for a folder instead of a file, simply replace the references to a file object in the samples above to folder objects. The webhook creation methods will accept file and folder objects. If a webhook event is applied to a folder, the webhook will also fire if the event is triggered on any files / folders under that folder.

The response object that will be sent through the callback function will contain an id, which may be used to update or delete the webhook programmatically at a later time.

Create a Webhook Using the App Dashboard

Other than creating a webhook programmatically through the APIs, you may also use the app developer dashboard to create webhooks manually.

Manually Created Webhooks

Webhooks that are created using the app dashboard will monitor changes to all files, folders, and objects within a user's account. You will not be able to specify a specific object to bind a webhook to. To create a webhook for a single file, folder, or object, you will need to use the Box APIs.

To manually create new webhooks through the app developer dashboard:

  1. Go to the App Developer Console and click to open the app that you would like to add webhooks for.
  2. From the left menu, click on Webhooks.
  3. At the bottom of the resulting page, click on the Create a new Webhook button.
  4. Enter the details and event types for the webhook that should be created, and click the Save Webhook button at the bottom of the page to save and activate the webhook.

You will now start receiving notifications any time those events are triggered on any objects within the user's account.

Update a Webhook

Typically a webhook would be modified if the events that should be listened for, or the URL where notifications should be sent to, are to be modified.

To add a new event to listen to, set the ID of the webhook and the new event trigger that should be listened to. With those values, make a request to update the webhook.

const webhookId = 'WEBHOOK ID';
const newTrigger = client.webhooks.triggerTypes.FILE.UPLOADED;
    
client.webhooks.update(webhookId, { trigger: newTrigger }, callback);

// Callback function
function callback(err, res) {
  // HANDLE ERROR CASE AND RESPONSE
}
import com.box.sdk.BoxWebHook;

String webhookId = "WEBHOOK ID";
BoxWebHook.Trigger newTrigger = BoxWebHook.Trigger.FILE_PREVIEWED;
        		
BoxWebHook webhook = new BoxWebHook(client, webhookId);
BoxWebHook.Info webhookInfo = webhook.getInfo();
webhookInfo.setTriggers(newTrigger);
webhook.updateInfo(webhookInfo);
const string webhookId = "WEBHOOK ID";
const string trigger = "FILE.PREVIEWED";
            
var newTrigger = new List<string>() { trigger };
var whr = new BoxWebhookRequest() { Id = webhookId, Triggers = newTrigger };
var updatedWebhook = await client.WebhooksManager.UpdateWebhookAsync(whr);
# Define webhook resources
webhook_id = 'WEBHOOK ID';
notification_url = 'https://www.YOURSITE.com/NEWNOTIFICATION';

# Define new webhook data
update_object = {
  'triggers': ['FILE.PREVIEWED'],
  'address': notification_url,
}

# Make request to update webhook
webhook = client.webhook(webhook_id=webhook_id).update_info(update_object)
# Define webhook resources
webhook_id = 'WEBHOOK ID';

# Define https request info
headers = {'Authorization': 'Bearer ' + client.access_token}
uri = URI.parse("https://api.box.com/2.0/webhooks/#{webhook_id}")
  
# Define new webhook data
data = '{"triggers": ["FILE.PREVIEWED"]}'

# Make request to update webhook
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
resp = https.put(uri.request_uri, data, headers)
json = JSON.parse(resp.body.to_json)
box webhooks update $webhook_id --triggers FILE.UPLOADED

Updating the Notification URL

To update the notification URL endpoint of a webhook in an update call, instead of setting trigger with an associated value, you would instead set address with the new URL.

Delete a Webhook

To remove notifications on a file or folder, you'll make a request to delete the given webhook.

Set the ID of the webhook that should be deleted, and make a request to the webhook delete method.

const webhookId = 'WEBHOOK ID';

client.webhooks.delete(webhookId, callback);

// Callback function
function callback(err, res) {
  // HANDLE ERROR CASE AND RESPONSE
}
import com.box.sdk.BoxWebHook;

String webhookId = "WEBHOOK ID";
        		
BoxWebHook webhook = new BoxWebHook(client, webhookId);
webhook.delete();
const string webhookId = "WEBHOOK ID";            

var result = await client.WebhooksManager.DeleteWebhookAsync(webhookId);
# Define webhook resources
webhook_id = 'WEBHOOK ID';


# Make request to delete webhook
client.webhook(webhook_id=webhook_id).delete()
# Define webhook resources
  webhook_id = 'WEBHOOK ID';

  # Define https request info
  headers = {'Authorization': 'Bearer ' + client.access_token}
  uri = URI.parse("https://api.box.com/2.0/webhooks/#{webhook_id}")
  
  # Make request to delete webhook
  https = Net::HTTP.new(uri.host, uri.port)
  https.use_ssl = true
  resp = https.delete(uri.request_uri, headers)
box webhooks delete $webhook_id

Next Steps

Related Resources