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.
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.
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.²
What Can You Build on the Platform?
There are two main buckets: apps just for you, and apps for everyone.
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.
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:
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.
The Bot User Flows:
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 email@example.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.
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.
pip install -r requirements.txt
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
secrets.shfile 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.
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.
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.
¹ 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.
⁵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!