Integrating with Slack APIs: Tips and Tricks

Slack, the business messaging and collaboration system, provides several APIs for its customers to build integrations with third-party systems. Integration devs commonly work with the Events API (outgoing webhooks from Slack), Web API (HTTP methods to manage data in Slack), and incoming webhooks (to send messages to a Slack channel).

We are visiting today with Taylor Reece, a Developer Advocate at Prismatic, to discuss some tips and tricks for developers who need to build integrations with Slack APIs.

Bru: Before we get into the details, Taylor, can you give us some context? Just how popular are the Slack APIs with our customers? And how are they using them?

Taylor: I'd say the Slack APIs are quite popular with Prismatic customers – who are B2B SaaS companies providing software for a huge variety of industries. While some APIs like Adobe Analytics are geared toward companies in a specific space (marketing), Slack's capabilities aren't tied to any one industry. So all sorts of companies are using Slack. The most common type of integration we see with Slack is a notification integration. Our customers can notify their customers through Slack when data changes in their B2B SaaS apps. We also often see our customers build Slack bots. Using the Events API, our customers can automatically capture and respond to messages that their customers send in their Slack workspaces.

Bru: Sounds like Slack integrations are providing value to many of our customers. That's great.

I've heard that the Slack Events API presents some challenges for endpoints. Is that the case, and how can devs best handle those endpoints?

Taylor: Yes, Slack does have some limitations with endpoints. Often, modern apps allow you to create customer-specific webhooks so that when Customer A does something in an app, it notifies Customer A's customer-specific webhook URL. But the Slack Events API is a bit different. It only lets you specify a single webhook URL for your app. As a result, you need to build additional logic for when you receive a message from Slack to determine which customer a given webhook payload is for and then route the data appropriately. One of the ways to do this is to create a shared endpoint, which is how we solve this issue on our platform.

Bru: Excellent. Moving on to auth, OAuth seems to be the ticket for Slack integrations. Is there anything special devs should know when working with it?

Taylor: For most of your Slack integration needs, you should be able to use OAuth 2.0. It lets you provide your customers with a one-button, straightforward UX to authenticate that just works.

Slack does offer something different for incoming webhooks. To make it work, your customer must generate a unique incoming webhook URL. These are commonly used for headless CI/CD systems, but that use case is less common on our platform.

One interesting thing you'll want to remember with Slack OAuth is that scopes are additive. For example, let's say you authorized a channels:manage scope. You might later pare the scope down to something simpler, but Slack simply adds both scopes together.

This can really mess things up with testing if you don't remember to revoke the scope and use only the permission set you've most recently requested. Slack has a really good explanation of how scopes work here.

Bru: What about Legacy OAuth? Should we still be concerned about that?

Taylor: When Slack was a much simpler app a few years ago, a user could get permission to do only a handful of things. As a result, those scopes gave you broad permissions, like read or post. Those permissions are still supported via Slack's Legacy OAuth functionality, and it's possible to run across older Slack integrations using these legacy scopes.

But, to avoid permissions issues, you shouldn't be doing any new development with Legacy OAuth – and if you come across Legacy OAuth in existing Slack integrations, we strongly recommend you figure out a way to replace it with the more granular permissions Slack provides. For example, rather than read you can request channels:read or groups:read.

Bru: Got it. On a somewhat related topic, can you tell us how Slack implements security for outgoing webhooks?

Taylor: When an event occurs in Slack and they send you a message, Slack signs its outgoing messages with something called HMAC (hash-based message authentication code). That helps you know that the message came from Slack, not some nefarious outside group. In addition to signing the message with a secret that you and Slack know, Slack also bakes in the timestamp for the message, which helps guard against replay attacks. You can look at the timestamp, and choose to reject the request if the timestamp is too old.

Interestingly, Slack isn't the only API that uses this extra bit of security. Calendly does something very similar.

Bru: But what if you have a legitimate reason for replaying a Slack integration? I know integration replay is something a number of our customers use.

Taylor: In that case, you can ignore the timestamp when you unpack the message. You'll still get the timestamp because Slack includes it in the HMAC, but you don't need to do anything with it.

Bru: That sounds easy enough. Speaking of easy, is it safe to call Slack's SDKs easy?

Taylor: Pretty much. Not all SDKs are truly helpful, but Slack's SDKs (like the one for Node.js) are really well-designed. They can save you a ton of time since you can get tab completion in your code editor and type safety as you pull down resources. Otherwise, if you code directly against their API, you'll need to figure out what parameters each endpoint requires, whether parameters need to be nested in another object, and so forth. I'd definitely recommend using Slack SDKs for development.

Bru: All right. Final question for today. What have you learned about building integrations with Slack that falls into the "makes things nicer or easier" bucket?

Taylor: If you really want to customize your user experience, message "blocks" are fantastic. You can do so much more with data presentation and formatting than the default plain text messages.

Bru: Most of us use the Slack app to chat with coworkers and customers, so plain text is familiar. How do blocks improve the user experience for Slack integrations?

Taylor: In addition to the standard Slack markdown, blocks support files, images, buttons, and all sorts of things. And you don't need to learn anything special to make it work. Each block is represented in the API as a JSON object.

You can use blocks individually or stack them together to create some pretty cool stuff for doing things like surveys and other brief forms. Check out a list of all the things you can do with blocks here.

Bru: Nice. Integration output often isn't attractive by default, but using blocks sounds like a pretty simple way to improve the UX for Slack integrations.

And that brings us to the end of today's discussion on using Slack APIs for integrations. Thank you, Taylor. I'm looking forward to seeing what we'll talk about next time.

If you want to see how Prismatic makes it easy to use the Slack APIs to build integrations with your B2B SaaS product, schedule a demo.