Webhooks V2

Introduction

Webhooks are triggers that you can attach to Box files and folders to notify you when those objects are accessed. You define the webhooks that you want to attach to a file or a folder and the URL that you want to notify. When events identified by the webhook occur Box responds by sending HTTP requests to the defined URL.

As an example, you can set up a webhook to notify you whenever a particular file gets updated or whenever files are downloaded from a particular folder.

Webhooks enable you to automatically monitor activity that affects your Box content.

Concepts

To create a webhook, you attach one or more event triggers to a target, associating them with an address.

A target is a Box object that supports webhooks. Currently the supported targets are files and folders.

An event trigger is the name of a type of action that affects a Box object and that can cause a notification to be sent. Examples of triggers are "FILE.UPLOADED" and "FOLDER.MOVED".

An address is a URL. When a Box trigger is activated, Box sends a notification message the address. The notification is an HTTP POST request. The address must be a valid HTTPS URL. The domain name must resolve to a valid IP address that is accessible from the Internet. It must not be a Box IP address.

Event Triggers

Box defines an extensive list of events that webhooks can watch for. For the complete list, see Event Triggers in the API reference.

Webhooks V2 Limitations

There are a few Webhooks V2 limitations:

  1. It is not possible to setup a webhook on a user's root folder. You can setup a webhook on any folder in Box besides the root folder.

  2. You can only set up one webhook per user per folder.

  3. You can only create 1000 webhooks for each application.

  4. The notification URL for a webhook must be a valid HTTPs URL that resolves to a valid IP address. The IP address must be accessible from the Internet and it most not be a Box.com address. The port used in the URL must be the standard HTTPS port, 443; if you use a different port then your notifications will not be delivered.

curl

To show how to create a new webhook and retrieve a reference to it we'll need a tool for sending GET and POST requests easily. We'll use curl.

Getting Started

You can create a webhook using an application's configuration page in the developer console. First, log in to your Box developer account and choose or create the application you want to use when creating the webhook.

In this example we'll assume that you plan to use an existing application.

1. Enable the scope labeled "Manage webhooks".

2. Create a developer token

Next, create a developer token that you can use to authenticate your API calls. The developer token is a developer-only token that you can use to bypass the OAuth2 authentication process during development and testing.

To create a developer token, open your application's configuration page and find the OAuth2 Parameters section. Near the bottom of the section, find the button labeled "Create a developer token". Click the button to generate a token. The text of the token appears above the button, replacing the text "You do not currently have a developer token".

Once you've generated a developer token you can use the text of the token in any interaction with Box that requires an access token. Your developer token is valid only for one hour. After the hour has passed you'll have to return to your app's configuration page and generate another token to keep working with it.

Note: In production use you must always use the standard Box OAuth 2.0 authentication procedure to authenticate your interactions with Box. Developer tokens are designed as a convenience for development and testing to make interaction with the developer console faster and more convenient.

3. Create a webhook

Using curl, send an HTTP POST request to api.box.com to create a webhook:

curl https://api.box.com/2.0/webhooks \
-H "Authorization: Bearer <DEVELOPER_TOKEN>" \
-H "Content-Type: application/json" -X POST \
-d '{"target": {"id": "<TARGET_ID>", "type": "folder"}, "address": "<NOTIFICATION_URL>", "triggers": ["FILE.UPLOADED","FILE.DOWNLOADED"]}'

Replace <DEVELOPER_TOKEN> with the text of the developer token that you created in step 2.

Replace <TARGET_ID> with the ID number that Box assigns to the file or folder that you want to use as the target of your webhook.

Replace <NOTIFICATION_URL> with the HTTPS URL you want to send notifications to.

If your target is a folder, change 'file' to 'folder' in the type field.

File and Folder IDs

If you're a Box user, you can get the ID of a file or folder by navigating to it. The ID of the file or folder is the long number that appears in the address bar of your browser. For example, in the URL "https://cloud.app.box.com/files/0/f/0/1/f_71281232313" the ID is 71281232313.

If you are a Box developer, but not a regular Box user, then you don't have access to the Box web UI. In that case you must use the Box API to find the file or folder you want and take the ID from the JSON object that represents it. For more about using the Box API to interact with Box content, see Getting Started with Box Integrations.

If your request succeeds then curl returns a JSON object that looks something like this (though the details of your webhook will be different):

{
  "id": "4165",
  "type": "webhook",
  "target": {
    "id": "5016243669",
    "type": "file"
  },
  "created_by": {
    "type": "user",
    "id": "2030392653",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "created_at": "2016-05-09T17:41:27-07:00",
  "address": "https://dev.name/actions/file_changed",
  "triggers": [
    "FILE.DOWNLOADED",
    "FILE.UPLOADED"
  ]
}

4. Retrieve your webhook

You can use curl to retrieve a reference to your new webhook by sending a GET request to the ID of the webhook under the Webhooks V2 API endpoint.

Here's an example, again using curl to send the request:

curl https://api.box.com/2.0/webhooks/4165 \
-H "Authorization: Bearer <DEVELOPER_TOKEN>" \
-H Cache-Control: no-cache

Again, replace <DEVELOPER_TOKEN> with the text of the developer token that you created in step 2.

5. Profit!

If your API call succeeds then curl returns a JSON object that contains a reference to the webhook that you created in step 3, above. The JSON object that you retrieve will be different from this example, but here's what a webhook object looks like when retrieved from Box:

{
  "id": "4137",
  "type": "webhook",
  "target": {
    "id": "5018848529",
    "type": "file"
  },
  "created_by": {
    "type": "user",
    "id": "2030392653",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "created_at": "2016-05-04T18:51:45-07:00",
  "address": "https://dev.name/actions/file_changed",
  "triggers": [
    "FILE.PREVIEWED"
  ]
}

Questions

If you have any questions, please post in our developer forum.

What's Next?

This tutorial shows how to use the Box API to create and retrieve webhooks. To learn more about how to use them, see the Webhooks V2 Reference.

Webhooks V2