Integrating REST APIs with webhooks and Realtime Code Hosting
Get a Twilio SMS whenever someone comments in your Trello boards
Realtime, the company I work for, recently launched a new managed cloud service called Realtime Code Hosting.
In a nutshell it allows you to host a REST API using an auto-scalable cloud platform. You write your API logic using Node.js JavaScript code, push the scripts to the Realtime Code Hosting Platform and you’ll instantly get HTTP/HTTPS REST endpoints to invoke the API.
Use these endpoints as callback URLs and you’ll easily integrate with third-party platforms providing webhook integration (a webhook is a method of augmenting or altering the behavior of a web page, or web application, with custom callbacks).
Let me give you a practical example.
You’re starting a new project with some friends and you need a web platform to keep control of what’s being worked on, who’s working on what, and where something is in the process. Since you aren't always connected to this platform 24/7, you want to receive real-time notifications in your phone whenever someone contributes to any particular task.
Challenge accepted.
First you’ll need to select a web collaboration tool. Enter Trello.
Trello is team collaboration tool that lets you organize anything and everything to keep your projects on task. Since Trello allows you to define a set of webhooks to receive notifications when a model changes (e.g. a board or a card), you just need to configure a Realtime Code Hosting REST API route to receive these notifications and when appropriate send a SMS message with the comment text.
SMS? Enter Twilio.
Twilio is an easy tool for developers to send and receive SMS and voice calls. It also provides a very simple REST API.
For our use case we’ll configure Trello webhooks to call our Realtime Code Hosting API and when the action is a new comment we’ll call the Twilio REST API to send the SMS. Easy.
Realtime Code Hosting configuration
The Realtime Code Hosting starting guide has all the details about activating your own Realtime Code Hosting Platform for free. For the sake of simplicity I’ll assume you already have activated your Realtime Code Hosting Platform and I’ll jump forward and create a REST route endpoint named trelloComment.
As a matter of fact we’ll need two endpoints with that name, since Trello will call one of them using the HTTP HEAD method when you’re setting the webhook (for validation purposes) and later will use a HTTP POST to notify you of model changes. All the details, including our comment text, will be in this POST request body.
The HEAD trelloComment script simply returns a 200 status code so Trello accepts the webhook callback URL. The Realtime Code Hosting JavaScript code will look like this:
The POST trelloComment script will be a bit longer since we need to validate if the triggered action is a new comment. If that is the case we’ll call the Twilio API to send the SMS message (you can check the Twilio Messages API details at https://www.twilio.com/docs/api/rest/sending-messages).
The JavaScript code will look like this (don’t forget to enter your Twilio account credentials and phone number in the appropriate places):
As soon as you push your trelloComment script to the Realtime Code Hosting Platform you’ll have a REST endpoint that will look like this:
https://codehosting.realtime.co/[REALTIME_APPKEY]/trelloComment
This will be the URL we’ll define as the Trello webhook callback URL.
Trello webhook configuration
Configuring Trello webhooks is not a walk in the park but it isn't rocket science either. You can find more details at the Trello webhooks documentation.
Assuming you already have your Trello token, key and idModel (the id of the model that should be hooked), you just need to send a POST to the Trello webhooks API route (it will look like the following one):
https://trello.com/1/webhooks/?key=[YOUR_TRELLO_KEY]&token=[YOUR_TRELLO_TOKEN]&callbackURL=https://codehosting.realtime.co/[REALTIME_APPKEY]/trelloComment&idModel=[YOUR_TRELLO_MODEL_ID]
Note that the callbackURL parameter is your Realtime Code Hosting trelloComment route URL.
If everything is OK you’ll get a 201 status code with a response stating your Trello webhook id. This means your Trello webhook is set and from now on whenever there is a change in the configured model your Realtime Code Hosting trelloComment route will be called. If the triggered action is a new comment you’ll receive a SMS notification in your phone.
Success!
All with just a few lines of JavaScript and without the need of managing any infrastructure whatsoever. Just three great services and APIs working together: Trello, Twilio and Realtime Code Hosting.
Wrapping-up
This is only a simple example of the level of custom integration between APIs that can be achieved through the Realtime Code Hosting platform. Many more could be presented.
I hope you found this interesting and that you feel inspired to build your own REST API using Realtime Code Hosting. If you have any interesting use case please share.
Happy coding.
