How to Add Integrations to a SaaS Product: A Practical Guide

A customer asks whether your SaaS product integrates with Salesforce.

Then another asks for HubSpot. Someone else needs Slack. An enterprise prospect wants Microsoft Dynamics. Your sales team adds Jira to the wishlist. A customer wants their data pushed into Google Sheets.

At first, each request looks like a small feature.

It isn't.

A production SaaS integration can involve authentication, API calls, data mapping, pagination, rate limits, webhooks, retries, background jobs, monitoring, permissions, customer configuration, and ongoing maintenance.

That's why the right question isn't simply “How do we connect our SaaS to another app?”

It is:

“What is the right way for our product to offer and operate this integration for every customer who needs it?”

This guide walks through the technical and product decisions involved in adding integrations to a SaaS product—from the first API call to production monitoring—and explains when it makes sense to build integrations yourself versus using integration infrastructure.

A customer-facing integration allows your users to connect your product to software they already use. For example, imagine you operate a customer-support SaaS platform.

A customer might want:

Your SaaS → HubSpot

When a support ticket reaches a certain stage, create or update a contact in HubSpot.

Or:

Your SaaS → Slack

When a high-priority ticket is created, notify a Slack channel.

Or:

Salesforce → Your SaaS

When a new opportunity is created, bring it into your application.

These are all integrations, but they have different technical requirements. A useful way to think about an integration is as a collection of capabilities:

• Connect the customer's account

• Authenticate securely

• Read data

• Write data

• Transform data

• Synchronize data

• React to events

• Handle failures

• Show status to the customer

The API request is only one piece of that system.

One of the easiest ways to waste engineering time is to start with the third-party API instead of starting with the customer use case.

Don't begin with:

“Let's integrate HubSpot.”

Begin with:

“What should a customer be able to accomplish with HubSpot?”

For example, your requirements might be:

1. Connect a HubSpot account.

2. Import existing contacts.

3. Create new contacts.

4. Update contacts when records change.

5. Trigger workflows when a contact changes.

6. Allow customers to map their fields.

7. Show whether synchronization is working.

Now you have something engineers can actually design.

The integration architecture should follow the capabilities your customers actually need.

A production integration normally has considerably more moving parts than its first prototype.

You need a secure way for a customer to authorize your application to access their account.

OAuth 2.0 is common for SaaS applications, although some APIs use API keys, personal access tokens, service accounts, or other authentication mechanisms.

OAuth itself isn't simply a “Connect” button. Your application needs to manage authorization, tokens, scopes, refresh behavior, and revoked credentials.

For example, Google's OAuth documentation notes that refresh tokens can expire or be invalidated under certain circumstances, meaning applications need to account for credentials becoming unusable.

Your application needs code that can communicate with the third-party API. That means handling:

• HTTP requests

• authentication headers

• request bodies

• response parsing

• status codes

• timeouts

• API versions

• API-specific behavior

Your application's customer object may not look anything like another application's contact object.

You might have:

Your SaaS
customer.name
customer.email
customer.company

while another application expects:

CRM
firstname
lastname
email
company

Now you need transformation and mapping logic. The problem becomes even more complicated when customers have custom fields.

Third-party APIs frequently return records in pages rather than returning every record in one request.

If a customer has 250,000 contacts, your integration needs to retrieve them safely without assuming everything fits in a single API response.

Pagination becomes especially important when implementing historical imports and synchronization.

APIs impose limits on how frequently your application can make requests.

For example, HubSpot documents account-level request limits for distributed OAuth applications, while Salesforce documents rate-limit considerations for its APIs.

Your integration therefore needs to understand:

• how many requests are allowed

• what happens when limits are exceeded

• how to back off

• when to retry

• how to prevent one customer from consuming disproportionate capacity

A 429 Too Many Requests response shouldn't become a customer-facing outage.

If the third-party application supports webhooks, you can receive events when something changes instead of constantly asking the API whether anything changed.

For example:

HubSpot
   ↓
Contact updated
   ↓
Webhook
   ↓
Your integration service
   ↓
Update your SaaS

But webhooks introduce their own engineering requirements.

You need to validate incoming requests, process events reliably, handle duplicates, deal with ordering issues where relevant, and retry failed processing.

HubSpot, for example, documents webhook retries when the receiving service fails, times out, or returns an error.

Third-party APIs fail.

Tokens expire.

Customers revoke access.

An API becomes temporarily unavailable.

A field disappears.

A request gets rate-limited.

A webhook arrives twice.

Your integration needs to know which failures are:

• temporary

• permanent

• customer configuration problems

• authentication problems

• provider problems

• bugs in your own code

That distinction determines whether you retry, ask the customer to reconnect, or alert your engineering team.

Once customers depend on the integration, “it doesn't work” isn't enough information.

You need to know:

• Which customer was affected?

• Which integration?

• Which operation?

• What request failed?

• What response did the provider return?

• Was the credential valid?

• Was the request retried?

• How many times?

• Did the integration eventually recover?

Without observability, your support team becomes the monitoring system.

Here is a practical implementation process.

Don't build integrations purely in the order customers request them.

Score each candidate based on:

Integration priority = customer demand + revenue impact + strategic value + reuse potential − implementation complexity

For example:

The exact formula isn't important. The discipline is.

It prevents an integration requested by one low-value customer from automatically jumping ahead of an integration that could unlock an entire segment.

Don't try to implement every endpoint immediately. Suppose you're integrating Salesforce.

You might initially support:

• create contact

• find contact

• update contact

• create opportunity

• update opportunity

• receive opportunity events

You may not need 500 Salesforce endpoints. The best first version is the smallest set of capabilities that solves meaningful customer problems.

Before writing code, document:

• authentication method

• required scopes

• available endpoints

• API versions

• rate limits

• pagination

• webhooks

• error responses

• object relationships

• custom fields

• bulk APIs

• provider-specific limitations

This becomes the technical specification for the integration.

A useful internal document might look like:

Integration: HubSpot

Authentication:
OAuth 2.0

Objects:
Contacts
Companies
Deals

Read:
GET contacts
GET companies

Write:
Create contact
Update contact

Events:
Contact created
Contact updated

Limits:
Per-account API limits

Failure handling:
Retry 429 and transient 5xx responses

Customer configuration:
Contact field mapping
Pipeline selection

Doing this before development exposes difficult requirements early.

The customer should be able to connect their account without giving your application their password.

For OAuth-based integrations, the flow generally looks like:

Customer clicks Connect
        ↓
Your application starts authorization
        ↓
Customer grants permissions
        ↓
Provider redirects back
        ↓
Your backend exchanges authorization code
        ↓
Access/refresh credentials stored securely
        ↓
Integration becomes connected

Keep credentials isolated by customer or tenant. Do not design your system as if there is one global HubSpot account.

Your SaaS may have 1,000 customers, each connecting a different HubSpot account.

Now implement the provider-specific communication layer.

Conceptually:

Your product
     ↓
Integration abstraction
     ↓
HubSpot connector
     ↓
HubSpot API

The connector should hide provider-specific details from the rest of your application where possible.

For example:

createContact()
updateContact()
findContact()
listContacts()

rather than spreading HubSpot-specific HTTP requests throughout your application. This makes the integration easier to test, replace, and extend.

Data models rarely match perfectly.

Your application may have:

Full name
Company
Email
Plan
Customer status

The external application might use:

First name
Last name
Company name
Email
Lifecycle stage
Custom properties

You need explicit mapping rules.

For example:

customer.email
      ↓
contact.email

customer.company
      ↓
contact.company

customer.status
      ↓
contact.lifecycle_stage

For customer-facing integrations, consider making some mappings configurable rather than hardcoding everything.

That allows different customers to use the same integration while accommodating differences in their setup.

There are two fundamentally different synchronization directions:

Push

Your SaaS
   ↓
External application

Pull

External application
   ↓
Your SaaS

You may also need bidirectional sync:

        ┌──────────────┐
        │              │
Your SaaS ↔ External App
        │              │
        └──────────────┘

Bidirectional synchronization is considerably more complicated because you need to reason about:

• conflicts

• source of truth

• timestamps

• duplicate records

• deleted records

• retries

• ordering

• idempotency

Don't build bidirectional synchronization simply because it sounds more complete. Build it when the customer workflow actually requires it.

Polling might look like:

Every 5 minutes:
“Anything changed?”

“Anything changed?”

“Anything changed?”

A webhook is closer to:

Something changed.
→ Tell us.

Webhooks can reduce unnecessary polling and improve responsiveness. But they aren't automatically simpler.

Your webhook system needs:

• public HTTPS endpoints

• authentication/signature validation where supported

• event validation

• idempotency

• retry handling

• event persistence

• monitoring

• replay/recovery strategies where necessary

For example, HubSpot's current webhook documentation requires a publicly accessible HTTPS endpoint and describes signature validation and retry behavior.

Your integration should assume failures will happen.

Consider a simple retry policy:

Request
   ↓
429?
 ├─ Yes → Backoff → Retry
 └─ No
       ↓
5xx?
 ├─ Yes → Retry
 └─ No
       ↓
4xx?
 ├─ Authentication → Reconnect
 ├─ Validation → Fix data/configuration
 └─ Other → Surface error

Do not retry everything. For example, retrying a malformed request 20 times doesn't make it more valid.

And be careful with operations that create records.

I

f the first request succeeds but your application doesn't receive the response, blindly retrying could create a duplicate record. That's where idempotency becomes important.

An integration isn't finished when the API works.

Your customer needs to understand:

• what the integration does

• what permissions they're granting

• whether it is connected

• what data is being synchronized

• how to configure it

• whether something failed

• how to reconnect

• how to disconnect it

A basic experience might be:

Settings
  ↓
Integrations
  ↓
HubSpot
  ↓
Connect
  ↓
Authorize
  ↓
Configure
  ↓
Connected

For more sophisticated products, you may need:

• an integration marketplace

• connection management

• field mapping

• workflow configuration

• sync history

• logs

• error messages

• alerts

The integration should feel like part of your SaaS—not like an unrelated developer tool bolted onto it.

Don't test only the happy path.

At minimum, test:

Authentication

• successful OAuth

• denied authorization

• expired credentials

• revoked credentials

API behavior

• successful requests

• malformed requests

• missing fields

• rate limits

• server errors

• timeouts

Data

• empty responses

• large datasets

• pagination

• custom fields

• unexpected values

Webhooks

• valid events

• invalid signatures

• duplicate events

• delayed events

• failed processing

Customer experience

• connect

• configure

• reconnect

• disconnect

• recover from failure

An integration that works in staging with one test account isn't necessarily production-ready.

The launch is the beginning of the integration's lifecycle, not the end.

Track things such as:

• connection success rate

• authentication failures

• API error rates

• webhook failures

• sync failures

• retry counts

• latency

• rate-limit events

• disconnected accounts

• successful workflow executions

You should ideally be able to answer:

“Which customers are affected right now, and why?”

without manually reproducing the problem.

Imagine your SaaS helps businesses manage leads. You want to add HubSpot.

The first version might support this workflow:

New lead created in your SaaS
            ↓
Find existing HubSpot contact
            ↓
Does contact exist?
       ↙           ↘
     Yes            No
      ↓              ↓
Update contact   Create contact
       \             /
        \           /
          Done

The engineering work behind that apparently simple workflow includes:

1. OAuth authorization

2. Credential storage

3. HubSpot API requests

4. Contact lookup

5. Field mapping

6. Error handling

7. Rate-limit handling

8. Duplicate prevention

9. Logging

10. Customer-facing connection status

And that's just one workflow.

If customers later ask for:

• companies

• deals

• custom properties

• webhooks

• bidirectional sync

• multiple pipelines

• historical imports

the scope grows again.

This is why integration engineering becomes difficult at scale: the number of integrations multiplies the number of provider-specific behaviors your team has to understand and maintain.

You don't need every integration. You need the right integrations.

A practical prioritization framework is:

How many customers are asking for it?

Is the integration blocking deals or expansion?

Does it help you enter a market or serve a key customer segment?

Will the integration solve a recurring need across many customers?

How difficult is the API?

How much infrastructure and provider-specific behavior will your team need to own?

A simple scoring model:

Score each integration from 1–5.

This gives product and engineering teams a shared way to decide what belongs on the roadmap.

Sometimes, yes.

Building an integration directly against an API gives you maximum control.

It can make sense when:

• you only need a small number of integrations

• the integration is strategically important

• the API is stable and straightforward

• you need functionality unavailable elsewhere

• the integration is deeply coupled to your core product

• you already have the engineering capacity to maintain it

But direct development means owning the entire integration lifecycle.

That includes authentication, API behavior, infrastructure, retries, webhooks, monitoring, updates, and customer support.

The initial API implementation is only part of the cost.

As Nango's current comparison points out, building from scratch means owning areas such as pagination, token refresh, rate-limit handling, schema mapping, scheduling, retries, dead-letter handling, observability, and tenant isolation.

There isn't one correct architecture.

Your engineering team builds every connector.

Best when:

• you need only a few integrations

• integrations are core product functionality

• you need maximum control

Trade-off:

You own development and maintenance.

A unified API abstracts multiple providers behind a standardized interface.

For example:

Your SaaS
    ↓
Unified API
    ↓
┌──────────┬──────────┬───────────┐
│ HubSpot  │ Salesforce│ Dynamics │
└──────────┴──────────┴───────────┘

This can work particularly well when your use case is narrow and standardized—for example, retrieving contacts across multiple CRM systems.

The trade-off is that normalized APIs necessarily abstract away some provider-specific functionality.

An embedded iPaaS provides integration infrastructure designed to be incorporated into your own SaaS product.

The architecture looks more like:

Your SaaS
   ↓
Embedded integration layer
   ↓
Customer connects apps
   ↓
Workflows / actions / syncs
   ↓
Third-party applications

This is useful when integrations are themselves part of your product experience.

Instead of building every connector, authentication flow and execution layer yourself, you use infrastructure designed to handle those concerns.

Current embedded iPaaS offerings commonly combine connectors, orchestration, customer-facing configuration and operational tooling.

This is often the most practical option.

For example:

Core product logic
       ↓
Your integration control plane
       ↓
 ┌───────────────┐
 │               │
Direct APIs   Integration platform
 │               │
Strategic       Long-tail
integrations    integrations

You might build your most important integration directly while using integration infrastructure for the long tail.

This avoids forcing every integration into the same architecture.

Instead of asking:

“Should we build integrations or buy an integration platform?”

ask five questions.

One or two is very different from 50.

If your product requires deep access to every provider's unique features, direct development may give you more control.

If you mostly need standardized capabilities, abstraction becomes more attractive.

If customers need to discover, connect, configure and monitor integrations inside your SaaS, you need more than backend API connectivity.

You need a customer-facing integration experience.

Ask who owns:

• OAuth changes

• API version updates

• webhook failures

• rate limits

• credential problems

• customer support

• monitoring

If the answer is “our existing product engineers,” include that opportunity cost in the decision.

If integrations themselves are your competitive advantage, owning more of the stack may make sense.

If integrations are primarily infrastructure customers expect your product to have, buying commodity infrastructure can allow your team to focus elsewhere.

The important point is that these approaches aren't interchangeable. A unified API and an embedded iPaaS solve different problems.

A workflow automation tool designed for internal employee automation isn't necessarily the right architecture for exposing integrations as part of your SaaS product.

And a direct API integration may be perfectly reasonable when you only need one strategically important connection.

The first integration can be built almost any way. The tenth integration forces you to establish architecture.

Avoid letting every connector invent its own conventions.

Define common concepts for:

• connections

• credentials

• actions

• triggers

• events

• jobs

• retries

• errors

• logs

Then provider-specific code sits underneath those abstractions.

Customer A's Salesforce credentials and data must never be mixed with Customer B's. Treat every connection as belonging to a specific tenant, workspace, organization, or user context.

Long-running syncs shouldn't block customer-facing HTTP requests.

A better pattern is:

User action
    ↓
Create job
    ↓
Queue
    ↓
Worker
    ↓
Third-party API
    ↓
Store result
    ↓
Update status

If an operation is retried, it shouldn't accidentally perform the action twice.

This matters particularly for:

• creating records

• sending messages

• charging payments

• triggering workflows

Don't wait until you have 50 integrations.

Store enough information to understand:

• what happened

• when it happened

• for whom

• which provider

• which operation

• whether it succeeded

• why it failed

• whether it was retried

The first API call is usually the easy part. The production system around it is where complexity appears.

An API may expose hundreds of endpoints. Your customers may only need five.

Start with the job to be done.

Successful authorization today doesn't guarantee valid credentials forever. Tokens can expire, be revoked, or otherwise become unusable.

Retries need to distinguish transient failures from permanent failures.

Rate limits should influence architecture from the beginning.

If five customers ask for essentially the same integration but you build five slightly different versions, you've created an expensive maintenance problem.

Build reusable capabilities and make customer-specific behavior configurable where possible.

A technically functional API connection isn't necessarily a good product integration.

Someone needs to own the integration after launch. That includes monitoring, updates, documentation and customer support.

If integrations are becoming a recurring product requirement, you don't necessarily need to choose between “write everything yourself” and “give up control.”

An embedded integration platform sits between those extremes.

For example, viaSocket Embed is designed for SaaS and AI companies that want customers to connect applications and use integrations inside their own product. Its current offering includes pre-built app connections, built-in authentication, an embeddable integration experience and workflow capabilities.

The important distinction is customer-facing integration infrastructure.

Instead of your engineering team separately building:

OAuth
+
Connect UI
+
Connector
+
Workflow execution
+
Retries
+
Monitoring
+
Customer configuration

you can use an integration layer that provides those capabilities and keep your own engineering effort focused on the product-specific logic.

Integrate Thousands of apps within your product.

viaSocket also supports a webhook-oriented approach where your application can send an event and trigger actions across a user's connected applications.

For AI products, integrations can also become tools rather than merely data-sync mechanisms. viaSocket's current AI offering allows connected applications to be exposed to AI agents as tools/MCP capabilities.

That distinction matters for modern AI SaaS:

Traditional SaaS

Your product
     ↓
Sync data
     ↓
Third-party app


AI SaaS

AI agent
     ↓
Choose tool
     ↓
User's connected application
     ↓
Take action

The right architecture depends on what your product actually needs.

Before calling an integration production-ready, check:

• Customer use cases are defined

• Integration is prioritized against other roadmap items

• Supported capabilities are documented

• Customer configuration is clear

• OAuth/API authentication works

• Required scopes are documented

• Credentials are stored securely

• Expired credentials are handled

• Revoked access is handled

• Reconnection flow exists

• Pagination is supported

• Rate limits are handled

• Timeouts are handled

• API errors are classified

• API versioning is understood

• Sync direction is defined

• Duplicate handling exists

• Idempotency is considered

• Deletes are handled where necessary

• Large datasets are supported

• Webhook endpoint is secured

• Signatures are validated where applicable

• Duplicate events are handled

• Failed events can be retried

• Event processing is observable

• Logs exist

• Errors can be investigated

• Alerts exist for important failures

• Customer connection status is visible

• Integration ownership is assigned

• Connect flow is simple

• Permissions are understandable

• Configuration is clear

• Errors are actionable

• Disconnect/reconnect works

• Documentation exists

The first integration can tempt you into thinking:

“We'll just connect our API to their API.”

That model works until your product has ten integrations, hundreds of customers, different authentication systems, changing APIs, thousands of webhook events and a sales team promising the next connector.

At that point, you're no longer maintaining API calls. You're maintaining an integration product. That's why the right architecture depends on the role integrations play in your SaaS.

If you need one or two highly customized connections, building them directly may be the right choice. If you need standardized data across a particular category, a unified API may be appropriate.

If integrations are becoming a customer-facing product capability across many applications, an embedded integration platform can take ownership of much of the infrastructure while your team focuses on the experience and business logic that differentiate your product.

The goal isn't to build the most integrations.

The goal is to give customers the integrations they need without turning your product roadmap into an integration-maintenance roadmap.