An Introduction to the Slack API: Easy-peasy Incoming Webhooks

These are the speaker notes from my talk Notifications and Beyond: An Introduction to the Slack API, first given at the APIDays conference in Sydney, Australia on March 1st, 2017. If you’re just here for the tutorial, skip to the end! You can use the repo linked here to set up a simple incoming webhook using a Python Flask server with very minimal coding.


Introduction

We live in a golden age a software, a time when knowledge workers have a host of top-notch products at their fingertips. But these myriad products come with a cost; the tools we use every day don’t always play nice together. That’s where the Slack platform comes in.
If you’re a software developer, chances are you make a product that teams need to communicate about. You can help simplify team coordination by building an app on Slack’s platform. Start by using the code linked at the bottom of this post to set up an incoming webhook for your team, and learn more about building a Slack app here!

Let’s start on a personal note

Before I worked at Slack, I managed large software installations for enterprise healthcare systems. I had to provide updates to people at different levels: c-suite, mid-level, clinical lead, entry level, etc.

1. Do work in various and sundry tools. 2. Use brain to brute-force work into human sentences of updates. 3. Write and re-write sentences in email for hours to different audiences on different to/cc/bcc lines to be sensible at different levels.

I used a LOT of tools to do this job. After the work was done, I spent an enormous amount of time synthesizing and restating the things I did in those tools in my email, and editing those emails to fit the needs of different audiences.

Many knowledge workers face this challenge; distilling and restating information from various sources, sending it off to the right people, and keeping responses organized in email threads can be exhausting.

The Slack platform can help you solve this problem.

The Slack Platform can unify updates from all the tools we use for work. When information comes from a single stream, it’s more digestible and less overwhelming because we don’t have to context-switch. And the less interruptions and context switches we experience, the more productive we become.²

Minimizing interruptions and context-switching is a good idea.

What Can You Build on the Platform?

There are two main buckets: apps just for you, and apps for everyone.

Slack App Directory

Apps just for you (and your team): These internal integrations are set up on a single team. For example, if you wanted to connect your personal website’s “Contact Me” page to your Slack team, you could use an integration to do that.

Apps for the Slack App Directory: Something to share! Apps built on Slack are third-party products that you can install and use right now¹. For example, the Google calendar app builds a bridge between your personal calendar and a Slack channel, so you can get meeting reminders without leaving Slack. We have over 900 apps in the directory and more coming every day.

There are many features you can build into an app, but here are three core concepts to get familiar with before you get started.

Slash Commands

Messages that begin with a slash are special in Slack — they can provide a way for users to interact with an app directly³. A user types in a command which requests some info from an app, and that app formats a response to Slack, which parses that response into a message.

The Slash Command Flow:

Bot Users

Want to know more about Howdy? Check it out here.

A bot user behaves almost like another Slack user on your team. In this example, you see the bot Howdy. Howdy runs “check-ins” or standups for your team and aggregates a daily status reports right in-channel. Bot users can do a variety of tasks like this , from filing expenses to scheduling meetings.

Bots connect to Slack in one of two ways: by listening for specific events using the Events API, or by setting up a persistent websocket connection using the Real-time Messaging API.⁴

The Bot User Flows:

Incoming Webhooks

These are notifications in Slack — when an event happens, they simply send some info into Slack. Instead of having to switch over to a calendar to see your next meeting, the Google Calendar Slack app can notify a channel or an individual of an upcoming meeting, so you can see information from other apps without leaving Slack. Woot! All your notifications in one place!

The Incoming Webhook Flow:

Start with an example: Twitter

Before you embark on your own incoming webhook adventure, first I suggest you try setting up the Twitter app on a test Slack team to get the feel of the thing. This is quite simple:

1. Open your Slack test team, or create one now.

2. Open Apps and Integrations Menu

3. Add a Twitter Integration

4. Choose the #channel in which you’d like your integration to post.

5. Log in to Twitter, tweet, and check your Slack team channel!

Build an Incoming Webhook

First, you should know that this exercise is in Python, uses a Flask server, and requires a basic understanding of how a simple HTML form posts to a route. If that sounds scary, I encourage you to try it anyway. One iteration of the final product can be found in the /final folder in the repo if you need to take a peek.

Start by cloning this repo and taking a look at the README in GitHub. You can work directly from the step-by-step instructions there. Refer back here for some helpful images and guidance.

git clone git@github.com:rooharrigan/slack_webhooks_intro.git

Head to api.slack.com, click Start Building, and create a new app.

Don’t worry about installing the new app on your team (you can do so if you like, but we’re just after a webhook URL at the moment). Look for the Incoming Webhooks menu, toggle webhooks on, click Add New Incoming Webhook to Team, and authorize that webhook to a specific channel on your team.

Activate Incoming Webhooks on your new app

Copy the newly generated Webhook URL onto your clipboard. Open up the slack_webhooks_intro repo in your favorite text editor and find the file called renametosecrets.sh. Do as the name suggests and rename the file to secrets.sh and make sure the old file is no longer open or in the repo. In secrets.sh, uncomment the second line of that file, and copy your URL into the waiting empty string:

WEBHOOK_URL = "https://hooks.slack.com/keepit/secret/keepit/safe"

Don’t put this URL anywhere on the internet! It contains a token, and that token is a secret. Keep it away from prying eyes; make sure you’ve added your secrets.sh file to your .gitignore file so you don’t accidentally push it to GitHub (steps here)⁵.

Back in your terminal, you’ve just got a few more steps to spin this thing up. Enter these five commands in this order:

# Create a virtual environment with the noted requirements and start your server.
   virtualenv env
source env/bin/activate
pip install -r requirements.txt
source secrets.sh
python server.py

If you see a message like this, your server is up and running.

Check out localhost:5000 in a Google Chrome window. It should look something like this! It won’t work just yet, but it’s very close.

Next, open up index.html in the /templates folder and start working your way through the in-line comments. For every new field you add to the form, make sure you are adding a line in the server.py file that handles that field in python. Now, leave this Medium article behind and work with your terminal, text editor, and the GitHub rendering of the README.md open on your screen.

Two things before you go:

  • If you’re trying to do this without writing any code, all you’ll need to do is open up /final, copy your WEBHOOK_URL into the secrets.sh file and source that file in your terminal, kick off your server, and head to localhost:5000. You should be able to use the form you see there to post a message into your Slack channel.
  • If you want to practice sending more detailed messages, try using our Message Builder. It’ll help you format your JSON correctly and show you how to use buttons.
Slack Message Builder

Congratulations! You’ve made it. I hope you were able to see something like this pop up in your Slack channel without too much trouble.

A friendly new notification.

Thank you to all the participants who have attended different iterations of this talk, and to all my incredible co-workers at Slack who work hard to make the platform a safer, simpler, and more delightful place for developers to try new things.

Footnotes

¹ Some of these third-party integrations were actually built in-house by the platform team Slack (Google calendar is one of those).

² Source: Harvard Business Review https://hbr.org/2014/05/quantify-how-much-time-your-company-wastes

³ There are lots of built-in slash commands too: typing / into your message pane will allow you to scroll through a list available to you.

⁴ For more on building bots, check out Easy-Peasy Bots: Getting Started or the Build This Bot workshop.

⁵Why do I have you do this renaming business? Because I want you to take a few extra moments to think about protecting your tokens. I’ve already added secrets.sh to the .gitignore for you already as a precaution. Keep those tokens secret!