Slack Webhook Integration

July 3, 2019 Seth Zimmerman

Well, well, well… Looks like we’ve got some new ossumnauts here who want to learn the      ins-and-outs of interplanetary communications! Oh? No? You’re just here to learn how to set up your ossum webhooks to receive Slack notifications? Isn’t that kind of the same thing...? Anyway, it’s great to have you aboard!

I’m going to assume you’re here because you’ve been using ossum and want to add an… *ahem*... awesome Slack integration that will notify you or your team when column/status changes happen to cards on your Planning board. If you haven’t signed up for ossum yet, no worries! Follow this link to create your free trial account today.

Let’s get on with the mission briefing; We want Slack notifications whenever a card changes columns within ossum. We can accomplish this with ossum webhooks! A webhook is a way for one application to deliver data to another application. Think of it as one of the ways that two different applications can communicate. In order for the two apps to communicate, though, there needs to be a “middle-man” of sorts, that structures and forwards the webhook data to the other application. So now it’s time to put on our spacesuits and navigate to another world! We’re heading to the world of Node.js.

Node is a runtime environment that allows you to run JavaScript directly on a computer/server. You might be asking: “Why do we need to travel to the world of Node?”. Well, if we’re going to set up a Slack integration, we’ll need that “middle-man” we talked about earlier to handle the incoming webhooks. If you look within the “Webhooks” settings page in ossum, you’ll see that an external URL is required. This URL represents an endpoint that can receive the incoming webhook data and push that data to Slack. We’re going to build a lightweight Node app that handles these webhook events. If you don’t have the dedicated infrastructure for this, don’t panic! For this tutorial, we’re going to use Glitch - it’s an easy to use cloud development platform that will deploy your code as you write it. We’ll have an external URL that can handle our incoming webhooks in no time!

To get our operation up and running, HQ has uploaded some boilerplate code for us to use (thanks HQ! 🧡). Go ahead and click this link to navigate over to our Glitch starter app. Find the button that says “Remix your own 🎤”, and click. 

Voilà! You should now see the boilerplate for our app. We’re starting out with a simple Node/Express app that, when visited at its root url, will return text that says “Hello ossumnaut!”. However, if we’re gonna get our webhooks up and running, we’ll need to create a dedicated route that can handle the incoming data. In server.js, on line 16, let’s create a new route called “ossum-webhook”.

app.post(`/ossum-webhook`, function(request, response) {

  console.log('Got an ossum webhook!');

});

Now that we have our route that is listening for POST requests at “/ossum-webhook”, let’s make it do more than just log to the console. Our “request” object within the callback is going to have all the webhook data in it, so let’s add in some variables to target the data we want to forward to Slack.

app.post(`/ossum-webhook`, function(request, response) {

  console.log('Got an ossum webhook!');

  const cardName = request.body.events[0].snapshot.Name;

  const cardNumber = request.body.events[0].snapshot.Number;

  const changeName = request.body.events[0].changes[0].name;

});

To get more info on how the webhook body is structured in ossum, take a look at our docs.

Now that we’ve got our data ready to go, let’s create our message! Slack uses markdown for their message content, so here’s a handy little function to help us format our message into something Slack can read. Place this on line 7, below the “body-parser” import.

const messageMarkdown = function(cardName, cardNumber, changeName) {

  return (`:satellite: _Incoming ossum Transmission..._\n*Card   changed:* ${cardNumber}: ${cardName}\n*Change type:* ${changeName}`)

};

We’ve got our route, and we’ve got a message string that Slack can read; let’s now write a request to Slack that will publish our message to a channel! We’re going to send this HTTP request inside of our route we created, so the entire block of code should now look like this:

app.post(`/ossum-webhook`,  function(request, response) {

  console.log('Got an ossum webhook!');

    const cardName = request.body.events[0].snapshot.Name;

  const cardNumber = request.body.events[0].snapshot.Number;

  const changeName = request.body.events[0].changes[0].name;

    axios.post('https://slack.com/api/chat.postMessage', {

    channel: process.env.SLACK_CHANNEL_ID,

    text: messageMarkdown(cardName, cardNumber, changeName)

  }, {

    headers: {

      Authorization: `Bearer ${process.env.SLACK_TOKEN}`

    },

    'Content-Type': 'application/json'

  })

    .then(res => {

    console.log('Slack got our message!');

    response.status('200').end();

  }).catch(error => {

    console.log('There was an error posting to Slack :(');

    response.status('500').end();

  });

});

You’ll notice there are some environment variables that we’re using (SLACK_TOKEN, SLACK_CHANNEL_ID), so you’ll want to get that information from Slack and input those variables into the .env file in your Glitch app. Follow this link for a handy step-by-step guide in how to obtain those values from Slack. You’ll only need to get to the “Picking the right conversation” section - by that point you should have both the TOKEN and CHANNEL_ID values that we need.

Because the source code is public within Glitch apps, we want to make sure we keep sensitive information hidden from other explorers. And since we’re on the topic of security, and just to be extra super secure, let’s add a super secret environment variable to our webhook endpoint that only you know about! We want to make sure no malicious space pirates can misuse our endpoint and send us a bunch of space junk. Go ahead and add in an environment variable to the .env file for your secret endpoint. Now, your endpoint should look something like this:

app.post(`/ossum-webhook/${process.env.SUPER_SECRET_ENDPOINT}`,      function(request, response) { ...

Now, all that’s left to do is to add our URL we created into ossum! Copy the live url link provided by Glitch. To get the live URL, check out the image below.

Time to pilot our starships back to ossum! Head over to your Account settings panel and navigate to the “Webhooks” settings. Paste your Glitch URL into the “Webhook External URL” input field (don’t forget to add “/ossum-webhook/[THIS_IS_WHERE_YOUR_SECRET_ENV_URL_GOES]” to the end!), and click the Save button. For more information on the Webhook settings page, check out our docs.

Once you’ve set everything up, try heading over to the Plan board and move some cards into different columns. You should be receiving notifications in your Slack channel that look like this: 

If it seems like your webhooks aren’t firing at all, make sure your webhook url is actually enabled; there is a limit to how many failed webhook deliveries our system will allow, so they may have been disabled while we were getting our app up and running.

And that is it! We’ve built a lightweight Express app, created a route that can handle our incoming ossum webhooks, formatted our Slack message, and sent the formatted message to one of our Slack channels! Well done, ossumnaut; it’s been an honor to explore with you. Now go forth with your Planning, Coding, and Delivery, and keep being ossum!

About the Author

Seth Zimmerman

Seth Zimmerman is a developer for ossum at CollabNet VersionOne. He has a passion for writing reusable code that looks so simple even a baby could read it. He is a lover of TypeScript, Angular, Node.js, overlyExplicitVariableNames, Google Keep notes, and wearing funky colored socks.

More Content by Seth Zimmerman
Previous Article
What Makes Ossum So Awesome?
What Makes Ossum So Awesome?

Achieve new heights of team productivity

Next Article
5 Things You'll Love About Ossum
5 Things You'll Love About Ossum

Choosing tools for your software development projects can easily become overwhelming. There are so many too...

One smart tool to plan, code, and launch software.

Try ossum