What are integrations, and how do they work?

All about how apps talk to one another

Jul 09, 2024

The TL;DR

Integrations are how two pieces of software talk to each other and share data.

Interoperability is the name of the game today: people expect their apps to be able to talk to each other and share information
Behind the fancy UI, most apps are just data: and through their public APIs, can you read (and maybe even write to) that data
Building and maintaining your own integrations with these tools can be complicated and risky (things can change at any time)
Startups like Paragon are building platforms that help developers automate the whole process

If you’ve created a GCal invite with a Zoom link or gotten a Slack notification about changes to a Salesforce status you’ve used an integration before. They’re everywhere!

This post is sponsored by Paragon, the best way to avoid the hassle of building and maintaining SaaS integrations. Paragon helps developers add dozens of native integrations to their apps quickly and reliably with just a few lines of code (and a click or two) and 70% less engineering resources required.

Try Paragon for free

What a (native) integration actually is

The apps you use every day are full of integrations. How do they actually work? How does Slack know when a Jira ticket changes status? How does Google Calendar create a Zoom meeting?

The answer has two parts, and we’ll run through each:

Integrations are data interchange: it’s two tools sharing or modifying data in each other
The way that this gets done on the technical side is through APIs

Let’s start with #1.

Integrations are data interchange

Sticking with our Slack notification example, what’s actually happening when a Jira ticket changes status and you get notified in a Slack channel?

It’s pretty simple:

When someone changes the status of a Jira ticket, that changes some data in the `tickets` table in Jira’s database
This change triggers Slack, and sends the updated data to Slack’s servers
The updated data (ticket name, status, etc.) is formatted and sent to the right Slack channel
(bonus) this data is stored in Slack’s database, too, like all messages are

This is an example of an integration that writes data – when the ticket status changes in Jira, data is actively sent to Slack, where it’s written to Slack’s database and shown in your #updates channel. Another good example of an integration that writes data is the GCal/Zoom integration: when you create a GCal event and click “add Zoom,” GCal is talking to Zoom’s servers, creating a new meeting, and adding that info to your calendar.

But there are also integrations that just read data. A good example is Salesforce’s integration with Gmail, which reads Gmail data so you can see the most recent points of contact with an opportunity. Integrations come in all shapes and sizes.

Integrations happen through APIs and Webhooks

Now, onto #2. The way that this integration data gets shared between two tools, whether they’re reading, writing, or both, is via APIs. We’ve written extensively about APIs before, both on a 101 level and more in depth. They’re the way that companies share data safely and securely, via a standardized interface so tools can actually talk to each other.

Let’s get more specific. Slack has a series of APIs for posting messages to specific channels. To post a message to a channel (assuming you’ve already authenticated properly), you’d do something like:

POST https://slack.com/api/chat.postMessage

// adding whatever you want to say in the message

And on Jira’s end, there’s a Webhook that will notify you when an issue’s status changes.

🧠 Jog your memory 🧠
A webhook is like an API, but in reverse: it actively publishes information when something changes. In Jira’s context, every time someone makes a change to an issue (or creates an issue, whatever you want), Jira will send a notification via API to any server that you tell it to.

And thus, with the combined alchemy of a Slack `postMessage` API and a Jira ticket status change webhook, we have an integration.

Native integrations vs. vanilla integrations

You’ve probably seen the term native in front of the word “integration” before. What this means is simply that the integration is actively built and supported by the tool you’re using, and doesn’t require you to do extensive custom work to get it running. Anyone (in theory) could use these two Slack and Jira APIs themselves to get this done – but that would be annoying. It’s much nicer when your tool builds this integration for you (like Jira and Slack), and you just need to configure some small things, like selecting which channel you want the bot to post in, or what different Salesforce fields mean in your app.

A screenshot of Paragon’s field mapping UI for native integrations

In the market today, customers are starting to demand native integrations and interoperability between apps – it’s pretty standard for most teams to have to start worrying about native integrations at some point. And integrations are amazing! PMs will tell you that they exponentially expand the number of things that SaaS products can do, and integrate them (no pun intended) even deeper into customers’ workflows.

On the flipside, building your own integrations is tedious, highly manual, and they usually end up brittle. We’ll talk more about this in the next section.

(Just musing here, one way of thinking about Zapier is that it’s for building all of the integrations that you wish were native to your tool, but aren’t.)

What it looks like to build your own integrations (and why it’s so hard)

Whether it’s you stringing together an integration yourself, or a team of developers building the scaffolding behind a native integration they’re creating, the process generally looks the same. I’ve been saying it’s hard and annoying, so let’s dive into why that is.

1) Start with your (or customer) requirements

The first thing you need to do is, well, figure out what you want to do. What data from other tools do you want to surface in yours? What actions do you want users of other tools to be able to take in yours? Simple enough, but hey, if it was self explanatory, product managers probably wouldn’t exist.

2) Handling authentication

One of the trickiest parts of building native integrations is authentication. Since your integrations will likely be using private data that belongs to your customers, you can’t just access it out of the blue; you’ll need to prove to the tool you’re integrating with that your customer wants to share their data back and forth.

Back to our Slack and Jira example, both of these apps are protected behind authentication, since it would be pretty bad if anyone could post in your Slack channels or see the statuses of your Jira tickets. Typically, tools will build UIs for their customers to configure authentication for their integration of choice, like Jira and Slack:

Why this is hard: every app handles authentication differently. From the type of authentication to how long the authentication lasts to the type of error that they give you if it doesn’t work, you’ll have to build different workflows for the different tools that you want to support.

For example, something like 50% of companies use a specific authentication scheme for their APIs called OAuth 2.0, but there are tons of other kinds to support, and even OAuth2.0 implementations can be wildly different. Error messages can be ambiguous. And again, if anything breaks, that can directly impact your customers.

3) Figure out which APIs are available and how they work

All integrations happen through APIs. Which means that if the tool you want to integrate with doesn’t have an API for the thing you want it to do, you can’t do that thing. The same holds true in reverse for your tool (although it’s in your control to change that).

For example, Slack doesn’t have an API for adding an emoji to your workspace unless you’re on Enterprise Grid. So there’s simply no way you can build an integration that does that (unless your customers are on Enterprise Grid). Good thing it’s probably not that important.

Once you’ve verified that your target tool has an API for what you need to do, you’ll have to figure out how that API actually works. What data does it require you to pass? And what data does it give you back? How often can you use it before getting throttled?

Why this is hard: every company’s APIs have their own unique quirks and gotchas. Some only return a portion of the data that you need, and others some have weird pagination schemes. Most APIs have what’s called a rate limit, which basically throttles you if you use it too quickly; so what do you do if a customer imports 10K Salesforce records all at one time? And like I said before, the API may not exist in the first place.

But that’s not all – APIs can even change over time! Companies can change the shape of their response, what fields it includes, really anything. And you may or may not get notified about this, which means it could break your whole integration (and ruin your customer’s day). In general, the larger the company, the more mature and stable their APIs will be; but ultimately there’s no guarantee that things will stay the same. This kind of change is referred to by developers as a breaking change, which is to say the change will break the code you have relying on it.

4) Listening for updates via Webhooks

Some integrations you’ll want to build require your app to react to changes in other apps. From Slack’s point of view, the Slack/Jira integration requires Slack to react to changes in Jira (a ticket status change). We’ve already seen that these changes happen through a technology called Webhooks: Jira sends out a notification to Slack that some data has changed, and Slack takes action.

Why this is hard: Webhooks have their own rules for using them. For Jira, you don’t just “get” Jira Webhooks so easy: you need to register it in the admin console (or via API), provide information like name and purpose, give it a URL to send data to, etc. And every company handles this slightly differently. And what happens if your application is offline, and misses a few Webhooks? What happens when Jira goes down and misses sending Webhooks?

5) Maintenance

In some senses, the most difficult part of building native integrations isn’t building them at all; it’s maintaining them. APIs, Webhooks, and authentication all have pieces that change over time, whether it’s a company updating how their API works, how long they let a user stay authentication for, or the policy when a Webhook consumer isn’t responding. Once you build an integration, it’s now your job to stay on top of all of these changes and make sure they don’t break your app.

Outsourcing your native integrations

Luckily for you (and especially PMs), in 2024 you don’t need to build native integrations from scratch. There are a bunch of different providers out there (including this post's sponsor, Paragon). So let’s run through each group of them, what they do for you, and why you might choose one over another.

Embedded iPaaS

This is an intimidating term that actually just means a platform that helps you build customer-facing, native integrations that look and feel like they’re part of your product.

Our sponsor, Paragon, is an embedded iPaaS. It comes with a classy UI (and an SDK with version controlled code, if you like) for building integration workflows. Here’s a screen grab from their docs about configuring a quick Salesforce integration:

They also provide an SDK for authentication and sending events that you integrate into your application code. And perhaps the niftiest piece is their white-labeled, prebuilt UI for your users to connect their 3rd party accounts and configure any user settings that you surface.

Behind the scenes, Paragon takes care of all of the gotchas we talked about earlier: changing APIs, complex authentication schemes, and the like. All you need to worry about is what you want your integration to do, and connecting Paragon to your application. iPaaS stands for integration platform as a service, by the way.

Unified API

The Unified API takes a very different approach to helping you build integrations. Instead of giving you a platform you embed in your app and configure on an integration-by-integration basis (like embedded iPaaS), a Unified API tries to shove all of the different APIs from the tools you want to integrate into a single one (hence, unified). It’s sort of like a universal language.

For a concrete example, let’s say you’re building an integration that lets your customers sync data with their CRM. There are tons of CRMs out there (Salesforce, Hubspot, Zoho, etc.). Instead of learning the nuances of each CRM’s APIs, a Unified API spec would define a universal concept like a “contact” and let you just do one API request to create one, translating the relevant details to each individual API. There are a few of these out there like Merge, APIdeck, and Unified.to.

In practice, Unified APIs have significant limitations and are usually limited to smaller scopes like accounting and finance.

Workflow automation and ETL

This one is pretty simple: you can use workflow automation tools like Zapier, or even ETL tools like Airflow or Prefect, to build integrations for your app. Zapier tends to be used more for internal integrations, less so for customer facing stuff. And ETL tools are typically built more for internal data platform / analytics use cases.

So with this group of tools, you usually end up needing to do most of the manual work we’ve talked about anyway.