5 Steps to Getting Started with Webhooks on UCL API
Webhooks are awesome, because instead of needing to make lots of HTTP requests to check for changes, UCL API will instead send an HTTP request to you when a change occurs.
In this guide, we’ll go through how to set up webhooks by building an app in node.js that shows all newly added or removed society room bookings.
Step 1: Create a new app in UCL API
Go to uclapi.com/dashboard, sign in, and click the big blue button to create a new app. Give it any name you like and click “Create”.
Step 2: Set up Glitch app
Once this is done, click the link below to create your own Glitch app.
Glitch is the friendly community where you’ll build the app of your dreams
We’ll use Glitch build our app, because it provides a convenient online node.js environment that requires little setup and is automatically deployed 🎏
Next, navigate to the server.js file using the sidebar on the right. You will see something like the screenshot below, although the app name towards the top left will be different.
The app we’re creating will be very simple in functionality. It will receive room bookings from UCL API on the /webhook endpoint, and store them in a list. When someone visits the homepage (/), it will display all the room bookings it has received from UCL API. That’s it!
We’re using the express framework to create a very simple web server. As it stands, our Glitch app is not functional. We still need to write the logic to receive UCL API webhooks. We do this by adding another express “route” below line 16 in server.js
app.post("/webhook", function (request, response) {});
Step 3: Security
The first thing we need to do here is make sure that not anyone can send data to this endpoint. All requests should come from UCL API. We ensure this by checking for the Verification Secret in the configuration settings of your app.
Navigate back to the UCL API dashboard and copy the verification secret
Then navigate to your Glitch app and paste it in the .env file as in the screenshot below. This is an environment variable, kept secret from anybody’s eyes in the .env file. If an attacker had access to this secret they could impersonate UCL API in your app, and send you malicious data, so you must keep this value secret 🔒
Now that the environment variable is set, go back to server.js and implement the logic to check for this value. We can do this by extending our express route
app.post("/webhook", function (request, response) {
if (
request.body.verification_secret !==
process.env.UCLAPI_VERIFICATION_SECRET
) {
response.sendStatus(401);
}});
Anyone sending a request to this /webhook endpoint will receive a 401: Unauthorized status message.
Step 4: Respond to UCL API challenge
Next, we need to prove to UCL API that the webhook URL we are setting up does indeed belong to us. We do this by adding the following bit of logic, which is outlined in more details in the documentation.
app.post("/webhook", function (request, response) {
if (
request.body.verification_secret !==
process.env.UCLAPI_VERIFICATION_SECRET
) {
response.sendStatus(401);
}
if (request.body.name === 'challenge') {
response.send({
challenge: request.body.challenge,
})
}});
Now that we’ve done all of that, we can complete the set up in the UCL API dashboard.
First, enter the webhook URL, which you can get by clicking the “Show Live” button in Glitch. Append /webhook to the URL that was newly opened. It should similar to the one below https://your-glitch-app-name.glitch.me/webhook/
Leave siteid and roomid blank and enter “Society” in contact, since we only want to receive Society room bookings in this app. Then, click “Update Webhook”. If all went well, a green checkmark should appear briefly next to the button.
Step 5: Store the incoming data
Final step! We now need to store the data from the webhooks UCL API sends us. In this case we use the simplest possible method and just store all content we receive in a JSON file. For now, that’s fine, but as your application becomes more sophisticated you probably want to move to a better storage system. To save the data in a JSON file, we extend our route with the following code:
app.post("/webhook", function (request, response) {
if (
request.body.verification_secret !==
process.env.UCLAPI_VERIFICATION_SECRET
) {
response.sendStatus(401);
}
if (request.body.name === 'challenge') {
response.send({
challenge: request.body.challenge,
})
}
if (request.body.name === 'bookings_changed') {
fs.writeFile(
'.data/latest_webhook.json',
JSON.stringify(request.body.content),
function(err) {
if(err) {
return console.log(err);
}
response.sendStatus(200);
});
}
});That’s it! Our app is now fully functional 💪 If you click on “Show Live” and refresh the page every once in a while, you will see society bookings show up.
That was a lot of work! So pour yourself a cup of tea, and take the rest of the day off ☕️
Link to Fully functional app (this is what your app should look like at the end of this guide)
Note: These bookings show up as they are confirmed by the UCL room bookings team. That means that likely no bookings will be added or removed over the weekend, so don’t expect any activity then.
For another example of how using UCL API webhooks works in practice, take a look at this python app, which powers live-roombookings.uclapi.com
We’re here to help! If you’re stuck or encounter any problems, comment on here, email us, tweet at us, or send us a message on facebook.
