Hooked on the Box Platform
Webhooks allow you to monitor Box content for events and send information back to your application. This opens up many new use cases and it can be the perfect complement for your app when it needs to be aware of what is happening on the Box Platform.
In this article we are taking the Dive into the Box Platform sample app and complementing it with the use of webhooks. You can find the demo app below in this GitHub repo.
If you remember from the first demo, a task was created for the dive master to verify the diving certification, the insurance, and the waiver signing. This will happen inside the Box web app, but we want to have feedback in our app when the dive master approves or rejects those documents.
Enter webhooks!
Box Platform Webhooks
You can create a webhook on an object, typically a file or a folder, and listen for specific triggers, for example FILE.UPLOAD or COMMENT.CREATE. Check the full list here.
Once the event is triggered, Box Platform will send the event payload to the URL you specify.
Creating a webhook
Just to show you another handy tool in action, I'm going to use the Box CLI to do this. If you haven't used the CLI before, make sure to check out the getting started with Box CLI quick start.
All content is stored under the bookings folder, and then organized by dive site, date, and diver.
We want to monitor updates on the task assignment, meaning, every time the dive master approves or rejects a document our app gets notified of that change.
We also want to track changes on the sign request, such as completed, rejected, etc.
In order to accomplish this we'll create a webhook on the bookings folder, which will track all content below it, and listen to the following triggers:
Verifying request authenticity
The first thing your app should do when receiving a webhook request, is to verify its authenticity.
Let's create a new entry point in our app to handle the request:
Once we have the request body, headers and the webhook_id we can use the built in method to check the signature:
The validate_message method will check the signature using both keys and will return true if one of them is valid. This will allow you to rotate one key at a time when you need to.
Setting up these keys is done on the webhooks page of your application in the Box developer console:
Handling the request
Once we get a valid request we can process it, here is the second part of the routes.py:
Each trigger has a slightly different payload. For this example I'm just grabbing the status of the event and updating the database for the specific document:
Updating the app
Once the app has the updated status on each document the we can implement visual queues to the user. Here is the end result:
