Getting started with Box Webhooks
Box as a big cloud content management provider is an ideal product to build up a central content platform for your company. Integrations between Box and other applications are an essential part in this story. Modern cloud based systems nowadays provide several ways to consume and manage the folder and files — Box is no exception here.
Box has a lot of different standard integrations and of course allows to integrate Box into your custom applications. To understand the different possibilities please visit the developer website of Box https://developer.box.com which is a really good starting point.
The site contains all important information about the central concepts of the platform like authentication, box objects and access to the different box SDKs in different languages (Node, Python, Java…).
In comparison to the REST API which provides a way to get data from Box on demand by a consumer, Box also integrates the webhooks concept to notify other applications about changes in the Box platform.
What are webhooks?
Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing.
Box webhooks are connected to a certain Box file or folder and are triggered for specified events which are created for certain user actions, e.g. the user uploads a new file or deletes a folder. Before Box starts sending webhook events, Box has to know the folder/file to watch for certain events and where to send the message - the http endpoint of your service.
How to register a new box webhook?
Box does not provide a user interface to create a webhook configuration. It allows us developers to create webhook configurations by sending a POST HTTP request with a certain JSON payload to the webhooks’ endpoint.
POST https://api.box.com/2.0/webhooks
{
"target": {
"id": "57468092918",
"type": "folder"
},
"address": "https://xxx.amazonaws.com/dev/box-webhook/12345",
"triggers": [
"FILE.UPLOADED",
"FILE.TRASHED",
"FILE.DELETED",
"FILE.RESTORED",
"FILE.COPIED",
"FILE.MOVED",
"FILE.RENAMED",
"FOLDER.CREATED",
"FOLDER.RENAMED",
"FOLDER.DELETED",
"FOLDER.COPIED",
"FOLDER.RESTORED",
"FOLDER.MOVED",
"METADATA_INSTANCE.CREATED",
"METADATA_INSTANCE.UPDATED",
"METADATA_INSTANCE.DELETED"
]
}
The above example describes the triggers which cause Box to send a message, the box folder is identified by an id and the publicly available http address of your service.
A full list of triggers can be found here: https://developer.box.com/reference#webhooks-v2-event-triggers
We can use Postman to create the webhook …
It is also possible to use the box CLI to create a webhook configuration very easily. Just use the below command with the correct arguments.
box webhooks create
More details can be found here https://developer.box.com/docs/box-cli
How does a webhook message from Box looks like?
Due to a missing standard of webhooks, every vendor defines its own format of data which is contained in the webhook message.
Imagine that the user XY uploads a new file into the monitored box folder, Box will send following message to your address above:
{
"type": "webhook_event",
"id": "8cb11f75-5e53-421a-89bc-10f699ccfe32",
"created_at": "2018-11-05T06:05: 03-08: 00",
"trigger": "FILE.UPLOADED",
"webhook": {
"id": "102709650",
"type": "webhook"
},
"created_by": {
"type": "user",
"id": "3926986238",
"name": "User XY",
"login": "userxy@fme-ag.de"
},
"source": {
"id": "344402180594",
"type": "file",
"file_version": {
"type": "file_version",
"id": "363741412994",
"sha1": "1721dcc7f40b7824dc688daf2974fc7f51796e12"
},
"sequence_id": "0",
"etag": "0",
"sha1": "1721dcc7f40b7824dc688daf2974fc7f51796e12",
"name": "Brochure_bmx.pdf",
"description": "",
"size": 13920862,
"path_collection": {
"total_count": 2,
"entries": [
{
"type": "folder",
"id": "0",
"sequence_id": null,
"etag": null,
"name": "Alle Dateien"
},
{
"type": "folder",
"id": "57468092918",
"sequence_id": "0",
"etag": "0",
"name": "Smartbox-Playground"
}
]
},
"created_at": "2018-11-05T06: 05: 03-08: 00",
"modified_at": "2018-11-05T06: 05: 03-08: 00",
"trashed_at": null,
"purged_at": null,
"content_created_at": "2013-05-21T02: 43: 30-07: 00",
"content_modified_at": "2013-05-21T02: 43: 30-07: 00",
"created_by": {
"type": "user",
"id": "3926986238",
"name": "User XY",
"login": "user-xy@fme-ag.de"
},
"modified_by": {
"type": "user",
"id": "3926986238",
"name": "User XY",
"login": "user-xy@fme-ag.de"
},
"owned_by": {
"type": "user",
"id": "3926986238",
"name": "User XY",
"login": "user-xy@fme-ag.de"
},
"shared_link": null,
"parent": {
"type": "folder",
"id": "57468092918",
"sequence_id": "0",
"etag": "0",
"name": "Smartbox-Playground"
},
"item_status": "active"
},
"additional_info": []
}Your application can evaluate the trigger value and run different code depending on the trigger. The json payload also contains a source block- it contains complete metadata about the object being uploaded or deleted. The id in the source block contains always the unique identifier of the box folder/file.
Best practices for Box Webhooks
- When your application gets called by Box with a webhook message, signal Box within 30 seconds with an HTTP status code 2xx that the webhook information was processed. If you wait too long, Box will send you the message again… and you have to filter duplicates.
- Box retries 10 times to deliver a single message when it was not confirmed by your application. After that Box does not try to send the message again. This webhook message will never reach you - so be prepared for that situation!
- Box will always send one event within one webhook message - it does not mix or batch events in a single message.
- Box does not provide a user interface to view the failed webhook messages- it is a good idea that your application which receives the webhooks, will persist these messages.
