Coding Fun – Webhooks

What’s a web-hook?  Here’s the Wikipedia definition.

Clear as mud?

I try to imagine these new concepts in the terms a Network Engineer would understand.  Ever dealt with firewalls, and state?  Know what an out of state firewall request is?  That’s a web-hook.

Web-hooks allow servers to send data in reaction to an event(in our case, the event we care about is a  message).  Traditionally applications had to open up sockets and sit idle listening for data, it was the only mechanism for two-way communication between systems.  Modern systems with an API, allow you to register a web-hook, allowing you to subscribe to updates you want.

Web-hooks have positives, and one glaring negative.  The major positive is that you only get data you care about, and can predictably process it.  In our case we can subscribe only to messages, and be fairly confident that when we receive one it was designated for us and we need to do something with it.

The glaring negative, you have to be reachable all the time.  Since Spark runs over the Internet, this means I have to have something Internet exposed listening for this data and ready to respond.  Reverse proxy helps here, as I can expose something with a minimal Internet attack surface, and yet still have an internal system respond.

Enough talk, let’s get to how we use them.

First, review this link.  We will be using the Spark API to actually register our web-hook, so no coding is required yet.  As a bonus at the end of this article I’ll like to how this can be accomplished in either Python or NodeJS to register future web-hooks.

First thing to do, list web-hooks.  Click the relevant link within the API, and turn on test mode (Look for the science-y beaker and toggle it to On).  This test mode allows us to run the API queries directly from the browser, a really great feature for one-off requests.

Once you’ve logged into the spark portal, it is going to automatically fill out the authorization information (more on that later).  You can simply click Run and on the right you should see information returned(likely empty {} or an empty items array).

Yay, you just ran your first API query against spark.  I wish it was all this easy.  Now we need to register a web-hook.  Again we are concerning ourselves with how our script will receive messages and act on them, so naturally we want to register a web-hook related to messages.  Click on Create a Webhook (either from the overview link, or the menu on the left side of the API detail page).

Most things are going to auto-fill themselves, we concern ourselves with 4 properties under the Request Parameters section:

create-web-hook-request-parameters

Oddly enough, these are the required parameters, funny how that works.

The name is purely for your sanity in listing them later, so you know what they do.  The resource is messages, and the event is created, which will likely be the defaults.

The targetUrl is the most important, this is what tells spark where to send data when it’s ready to send your bot a message.  Importantly, bots cannot just listen passively in a channel/space, they must be mentioned.  Private messages and mentions are what Spark is going to act on, and when it does it’ll send it to the Url you define here.

Once you’ve defined everything, click Run, again you should see the output in your browser(along with the request!).  This information is in JSON format.

create-web-hook-result

If you get any other result than 200 / success, and a series of what look like random strings(they aren’t, it’s just unique identifiers) go back and ensure you have filled out everything required.

You should now be able to send your spark bot messages, without even a single line of code running!

Obviously we need to setup the actual listener (in our case NGINX will serve this) and the script in the back-end.  Those will be detailed in a future posting.

2 thoughts on “Coding Fun – Webhooks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s