Slack integrations are awesome. But what if the functionality you want isn’t already there in the list of available services? This tutorial shows you how to set up a custom /highfive command so your colleagues can shout you out for being awesome. And others, of course. But they’ll want to high-five you first.
What we want
At Kahoot! our success is made up of a lot of small achievements that could easily go unnoticed, especially in a globally distributed company. Johan, our CEO, asked me to build a way to shout out fellow Kahooters when they do something awesome.
So now, when I type /highfive Eivind for debugging the vagrant boxes, the following will be posted to a dedicated channel:
This tutorial takes you through the plumbing necessary to make this happen. You’ll need to be an admin of your Slack team in order to set up the integrations, and you’ll need a GitHub account for the microservice.
Setting up an incoming webhook in Slack
Go to the Slack admin panel, click Add Integrations, then click Incoming Webhooks. Select the channel you want your high fives to be posted to (I’d recommend creating a new one), and choose a name and emoji.
The important bit here is the Webhook URL. Your hook.io microservice will be sending HTTP POST requests to this URL, so note it down now.
Once you’ve saved your incoming webhook, you can test it using cURL on the command line:
curl -X POST --data-urlencode 'payload={"channel": "#high-fives", "username": "curlbot", "text": "This is posted to #high-fives and comes from a bot named curlbot.", "icon_emoji": ":space_invader:"}' $WEBHOOK_URLwhere $WEBHOOK_URL is the URL Slack generated for you.
You should see a message pop up in the #high-fives channel.
Creating the slash command
cURL is great, but you can’t do it from inside Slack, so we’ll need a slash command your users can type to trigger the high fives.
Add another integration, this time of the Slash Command type. The important thing to note is the auto-generated Token, which is what your hook.io microservice will use to identify that the request came from Slack. Set the Method to POST, and leave the URL for now — you’ll fill this in when you’ve created your microservice.
While you’re here, take a look at the Outgoing Data format: this shows that the data that will be POSTed to your microservice will look like so:
token=$TOKEN
team_id=T0001
team_domain=example
channel_id=C2147483705
channel_name=test
user_id=U2147483697
user_name=Steve
command=/weather
text=94070Writing a hook.io microservice
hook.io is a great little product that lets you build HTTP microservices in JavaScript. If you haven’t already, sign in to hook.io with your GitHub account.
If you just want to get your hook up and running as soon as possible, you can fork my highfive hook by going to https://hook.io/kmoe/highfive/fork and setting the environment variables below. If you want to configure it yourself, read on!
Click on Create Hook and fill in the Hook Name with whatever you like. Leave the Hook Path blank. Now is a good time to create a blank Gist to store your source code and link to it in the Source Code field. Finally, apply the ‘debug’ theme — this will allow you to visit a friendly HTML page for your hook and see its output.
You’re almost ready to code! The last thing we need to do is set some Environment Variables. These are variables stored privately by hook.io that you can use within your hooks. We’ll use these to store the Webhook URL and Token we recorded earlier, so we don’t expose these in a public Gist. This means that even if someone stumbles across your source code, they won’t be able to post to your Slack.
Go to hook.io/env and set highfive_token and highfive_url to the Token and Webhook URL respectively. These are used in the code below as properties on hook.env.
Now put the following in your Gist:
This code constructs an HTTP POST request using the URL stored in your environment variables, along with the user_name and text passed in as parameters by the Slack slash command.
Connecting it all together
Finally, go back to your Slash Command integration page and add the URL of your hook. You should now be able to type /highfive [name] for [achievement] in Slack and see the message appear in #highfives.
Conclusion
Congratulations, you just deployed a JavaScript microservice and connected it securely to Slack. High five!
