Webhooks V1

Webhooks are triggers that you can add to an application that watch for changes to a user's account. When a monitored object changes, Box notifies your application of the change.

Webhooks Note

V1 webhooks, created in the application configuration page, monitor all objects in a user's account. V2 webhooks, created using the Webhooks V2 API, monitor individual files and folders that are specified when a webhook is created.

Webhooks V2 provide a different way to create and manage webhooks. V2 webhooks cannot be created using the application configuration page; instead, you must use the Webhooks V2 API to create and manage them.

For more information about Webhooks V2, see Getting Started with Webhooks V2.

To create a webhook, begin by editing your application:

To create a webhook that watches for all changes to a user's account, find the Webhooks section of the application's configuration page and click the button labeled "Create a New Webhook".

Box displays the Webhook V1 configuration page.

On the configuration page, enter the name and description of your new webhook.


A webhook marked "Development" is triggered only when your application is executed with your developer account.

A webhook marked "Online" is triggered when any user executes your application.

Please contact us to have your webhooks switched to ‘Online’.

Select the event triggers that you want the webhook to monitor. When a monitored event occurs, Box sends a notification to the endpoint URL that you specify.

Alert: Currently ‘Downloaded’ and ‘Previewed’ events will not be returned for the user requesting the webhook, but will be returned for any collaborators.

Enter a URL in the text box labeled "Endpoint URL". When your webhook is triggered by a monitored event, information about it will be sent to the URL you enter. You can configure the webhook to send a REST request, an XML message, or a SOAP message to your endpoint.

The URL that you supply must be a valid HTTPS URL that designates a web service that can accept and handle the notifications that Box sends.

Choose the information about monitored events that you want Box to send to your endpoint. The notification sends this information in callback parameters:

Each callback parameter becomes a field in the notification data sent to your endpoint.

The dropdown menu labeled "Parameter value" lists Box parameters that you can choose to include in the notification. For example, you might choose to send user ID, file name, file ID, and so on. You can also enter a custom parameter of your choice.

After you've added all the callback parameters you want to send to your endpoint, click the Save Webhook button to create and activate the webhook.

Your webhooks will be triggered only if your application is used by a Box user. To test them you can add your application to your Box account. If you've published the application in the Box App Gallery then you can visit the gallery and add the application from there.

Alternatively, you can visit https://app.box.com/services/YOURAPPNAME or https://cloud.app.box.com/developers/services/edit/ to add an application to your account.


If your application's name contains spaces then Box replaces the spaces with underscores ("_") in the URL at https://app.box.com/services/.

If you have any further questions about how webhooks work, see this simple node.js app we put together or visit our developer forum.

Webhooks V1