Skip to main content
DBB Software logo

API Integration Best Practices for SaaS Products

SaaS engineering

Product development

Updated: November 16, 2026 | Published: November 15, 2026

Key Takeaways

  • Design every stage of a customer connection, from consent to disconnect, for changes you don't control: tokens, permissions, data, provider rules and traffic keep changing after the first connection works.

  • Build token refresh per provider, because lifetimes, idle limits and rotation rules differ, and let only 1 refresh run per connection at a time: under rotation, 2 at once can lock a customer out.

  • Treat every webhook as a signal to verify, store once and reconcile. Shopify's webhook documentation says delivery "isn't always guaranteed", so a scheduled reconciliation job has to catch what never arrives.

  • Give each customer its own share of rate limits and queues, so 1 customer's large first import can't stall syncs for everyone else.

  • Show each customer a connection status built from recent sync results, because a stored token says nothing about whether data still flows.

In late 2026, Salesforce rolled out a 30-day expiry for unused refresh tokens to every app connected to its customers' orgs. An admin on r/salesforce blamed that change for sync issues with no errors anywhere in Salesforce, and concluded that every app had to be reconnected, "Even if the program/tool/app says the connection is active."

A third-party API integration in a SaaS product has to keep working for every customer as permissions, tokens, data, provider rules and traffic change, and it must recover safely when something breaks. This guide follows 1 customer connection through 6 stages: Connect, Synchronize, Recover, Operate, Verify and Disconnect.

For each stage, you'll find what to build, why it matters and how to check it. The guide ends with a SaaS API integration checklist you can run before each release and after every provider change.

It draws on integrations DBB Software has built: payment integrations for a creator live-streaming app, an integration for each of SafeMode's fleet clients built on reusable templates, and Uniform's integration framework, with plugins for content management, product information, digital asset and search platforms.

What Are the Main API Integration Challenges in a SaaS Product?

The main API integration challenges in a SaaS product continue long after the first connection works: tokens expire on each provider's schedule, webhooks arrive twice or not at all, 1 customer's traffic slows everyone else's, each customer configures the integration differently, providers change their rules, and customers leave.

Several of these arrive with no change to your code. In 2025 and 2026, Slack changed its rate limits, Xero capped connections and Salesforce changed its token rules for third-party apps. The upkeep adds up: in Paragon's 2026 survey of 600 B2B SaaS leaders, 68% said maintaining integrations takes 25% or more of their engineering time. Paragon sells integration tooling, so read that as a vendor's figure.

If you buy a platform, it can take over token refresh, rate-limit handling and webhook formats for the providers it supports. A unified API puts many providers behind 1 interface, and an embedded integration platform runs integration workflows inside your product.

The decisions about each customer still stay with you:

  • Their field map

  • The status they see

  • Who fixes a broken connection

  • What happens to their data when they leave.

So the practices below apply on a platform too.

Connect: Scopes, App Review and Token Refresh

Connecting a customer means requesting the right scopes, clearing each provider's app review and keeping that customer's tokens valid.

Ask for the Narrowest Scopes, and Plan for App Review

Ask each customer only for the scopes your features use, and put each provider's app review on your launch plan, because a review can take weeks.

Scopes are the permissions your app requests through OAuth, the standard that lets a customer grant access without sharing a password. Broader scopes cost you twice, in review before launch and in approvals at each customer:

  • Review time: Google's verification for restricted scopes takes "several weeks" and needs a Cloud Application Security Assessment (CASA) by an approved assessor, renewed at least every 12 months. Restricted scopes are Google's most sensitive tier.

  • Who has to approve: in Microsoft Entra ID, app-only permissions are the ones your app uses when no user is signed in. They always need a tenant administrator's consent, so an ordinary user at your customer can't connect the integration alone.

Letting each user connect their own account also takes work off your support team. At Tie, DBB helped build the integration apps that let users connect their own Klaviyo and Google Ads accounts. The apps ended the support team's back-and-forth over API keys with each new user.

To check it, list every scope you request next to the feature that needs it, and drop any scope with no feature beside it.

Refresh Token Best Practices for Customer Connections

Store 1 token set per customer connection, plan for each provider's expiry and idle limits, and let only 1 process refresh a connection at a time.

An OAuth refresh token gets your product a new short-lived access token without asking the customer to sign in again, until the refresh token itself expires or is revoked. Some providers also rotate refresh tokens: each refresh returns a new one and retires the old one, at once or after a short grace period. As of November 2026, these 5 providers end a connection under different rules, so a single refresh routine won't fit them all:

Provider

Token rule

What it means

Google

Idle limit: a refresh token ends after 6 months unused. In Testing status, it ends after 7 days, unless the app asks only for basic profile scopes.

Publish the app before customers connect, and expect a reconnect after 6 months unused.

Microsoft

Lifetime: 90 days (24 hours for single-page apps). Each refresh issues a new refresh token with its own 90 days, and the old one stays valid.

Keep only the newest token, and expect a reconnect after 90 days unused.

Slack

Rotation, which can't be turned off once on: access tokens expire after 12 hours, and a used refresh token is revoked after a short grace period.

Refresh as each access token nears expiry.

Salesforce

Idle limit: 30 days, rolled out to every app in customer orgs from 21 October 2026 (sandboxes) and 4 November 2026 (production). Partner apps used in more than 2 customer production orgs must also rotate, and reusing a replaced refresh token invalidates the current one.

Plan a reconnect for connections idle for 30 days.

Shopify

Expiring offline tokens: access tokens last 1 hour, and refresh tokens last 90 days and rotate. Public apps still on non-expiring tokens are rejected from 1 April 2027.

Save each new refresh token at once, and move a public app to expiring tokens before April 2027.

Sources: the Google, Microsoft, Slack, Salesforce and Shopify documentation, checked in November 2026.

  • Store the newest token set: save each new refresh token as soon as a refresh returns it. Microsoft's refresh token documentation adds: "Securely delete the old refresh token."

  • Plan for idle limits: a connection left unused past a provider's idle limit loses its token, and refreshing just to keep it alive isn't the answer. Salesforce's guidance for its 30-day limit asks integrations not to "create artificial refresh activity solely to prevent token expiration." Refresh during real syncs, track each token's idle time, and ask the customer to reconnect when one lapses.

  • Allow 1 refresh at a time: under rotation, 2 refreshes for 1 connection can end it, because the second sends a refresh token the first has just retired. Macha's 2026 post-mortem describes 2 webhooks refreshing the same Zendesk token at once and locking a customer out: "Refresh-token rotation turns a benign race into a fatal one."

Macha's fix was "re-reading the stored OAuth credentials inside the per-subdomain lock". That lock has to hold across every server and worker that can refresh, so it can't be kept in one server's memory. In this TypeScript and Postgres sketch, each process locks the connection's row and re-reads the token. If another process refreshed it while this one waited, it uses that new token instead of refreshing again:

// Sketch: `db` is any Postgres client with transactions; `provider.refresh` calls the token endpoint.
// After a 401, pass the token that was rejected, so the function refreshes it even before its expiry.
async function getAccessToken(connectionId: string, rejectedToken?: string): Promise<string> {
  return db.transaction(async (tx) => {
    // FOR UPDATE waits while another instance holds this row, then reads what that instance saved.
    const conn = await tx.one(
      'SELECT access_token, refresh_token, expires_at FROM connections WHERE id = $1 FOR UPDATE',
      [connectionId],
    )
    const stillValid = conn.expires_at.getTime() - Date.now() > 60_000
    if (stillValid && conn.access_token !== rejectedToken) {
      return conn.access_token // still valid, or another instance just refreshed it
    }
    // The row stays locked during this call, so keep its timeout shorter than
    // your database's lock, statement and idle-transaction timeouts.
    const fresh = await provider.refresh(conn.refresh_token, { timeoutMs: 10_000 })
    await tx.none(
      'UPDATE connections SET access_token = $2, refresh_token = $3, expires_at = $4 WHERE id = $1',
      // Some providers return a new refresh token on every refresh, and some don't.
      [connectionId, fresh.accessToken, fresh.refreshToken ?? conn.refresh_token, fresh.expiresAt],
    )
    return fresh.accessToken
  })
}

A lock in a shared store such as Redis works too, if its expiry outlasts the refresh call and the token is re-read inside it.

When a call returns 401 Unauthorized, refresh the token once by passing the rejected token to getAccessToken, then retry the request once. If the provider rejects the refresh, or the retry gets another 401, stop and mark the connection for reconnect. More retries won't bring back a revoked grant, the access the customer gave you.

A refresh can also fail without a clear answer after the provider has already issued new tokens: the response times out, or your save fails. Retry with the stored token, because most of these providers still accept the old one: Microsoft keeps it valid, Slack accepts it for "a short grace period", and Shopify until you use the new token. Salesforce's rotation invalidates the old token at once, so if the refresh went through, the retry returns invalid_grant.

If the retry after a lost refresh returns invalid_grant, you may have lost a newly rotated token, or the customer may have revoked access. Stop retrying, mark the connection for reconnect and alert your team.

To test the lock, start 2 refreshes for the same test connection at once: the connection should still work, and the provider should receive 1 refresh.

Synchronize: Webhooks and Per-Customer Field Mapping

Synchronizing means getting each customer's data across correctly: webhooks for changes as they happen, a scheduled reconciliation job that catches what webhooks miss, and a mapping that fits each customer's setup.

Webhook Best Practices: Verify, Deduplicate and Reconcile

Verify every webhook signature on the raw request body, store each event once, respond fast, and reconcile against the provider's API on a schedule.

A webhook is an HTTP request a provider sends to your product when something changes, such as a new order. Providers don't promise each event arrives once, in order, or at all:

  • Shopify's webhook documentation says delivery "isn't always guaranteed", and tells apps to run reconciliation jobs.

  • A webhook retry has limits. Shopify's webhook delivery guide says it retries a failed delivery 8 times over 4 hours and deletes an Admin API subscription after 8 failures in a row, so those events stop arriving.

  • Stripe doesn't guarantee that events arrive in the order they were generated.

A signature proves that a request came from the provider unchanged. Verify it with the provider's own library where one exists, because the library also checks the timestamp that stops an old request from being replayed. Stripe's libraries reject a timestamp older than 5 minutes by default and need the raw request body, so your framework mustn't parse it first:

// Sketch with Express and the Stripe Node library.
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: Stripe.Event
  try {
    // Checks the signature against the raw bytes, and the timestamp against the tolerance.
    event = stripe.webhooks.constructEvent(req.body, req.header('stripe-signature') ?? '', endpointSecret)
  } catch {
    return res.sendStatus(400) // bad signature or an old timestamp
  }
  await storeEvent('stripe', event.id, event) // the insert in the next sketch
  res.sendStatus(200) // answer before any slow processing
})

The handler rejects a bad signature or an old timestamp, stores the event and answers at once, leaving the slow work for later.

Where a provider has no library, follow its docs for exactly what it signs, and compare signatures in constant time. GitHub's docs say "Never use a plain == operator" and point to functions such as crypto.timingSafeEqual.

Store each event once, keyed on the provider's event ID, before you process it. Then have each worker take the oldest unprocessed event that no other worker holds, and process it in a transaction that also marks it done:

-- On receipt: store the event once. A duplicate delivery inserts nothing.
INSERT INTO inbound_events (provider, event_id, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (provider, event_id) DO NOTHING;

-- In a worker: claim 1 unprocessed event and process it in a single transaction.
BEGIN;
SELECT id, payload FROM inbound_events
WHERE processed_at IS NULL
ORDER BY received_at
LIMIT 1
FOR UPDATE SKIP LOCKED;  -- other workers skip this row instead of waiting for it
-- ...apply the event's changes to your own tables here...
UPDATE inbound_events SET processed_at = now() WHERE id = $1;  -- $1: the id claimed above
COMMIT;  -- a crash before this line rolls everything back, and the event is processed again
-- Track attempts per event, and set aside one that keeps failing,
-- or the oldest-first order hands it to every worker in turn.

The unique key on its own only stops 2 deliveries from becoming 2 events. Reliable processing comes from the transaction, where the changes and the "done" mark commit together or not at all.

A call outside your database, such as another API or an email, can still run twice if a worker crashes between that call and the commit. Give that call its own idempotency key, a unique value that lets the receiving side ignore a repeat.

Because events can arrive out of order, treat each webhook as a signal that something changed. When order matters, fetch the current object from the provider's API instead of trusting the payload. Then reconcile on a schedule: compare what you hold with the provider's current data, and fix the differences.

Webhook subscriptions can also lapse unnoticed. Microsoft Graph subscriptions expire, and Workwae's 2026 write-up notes that with a quiet mailbox, nothing warns you first. So Workwae renews its subscriptions on its own schedule and polls the API as a backstop.

DBB built webhook handling this way for payment integrations in a creator live-streaming app. A dedicated webhook service kept each Stripe request's raw body, checked the signature on it before anything else ran, and passed valid events to Kafka. Each service committed a message only after its handler finished, so a crash midway left the message to be processed again.

Your webhook handling passes when the same event, sent twice at once, changes your data once, and an event you drop on purpose shows up after the next reconciliation run.

Keep a Field Map and Sync Settings for Each Customer

Keep a field map and sync settings for each customer connection, because no two customers set up the same provider alike.

Store these per connection, as data the customer or your team can change without a deploy:

  • Field map: which of the customer's fields feeds which of yours, custom fields included.

  • Value map: how their picklist values and statuses translate into yours, with a default for a value you haven't seen before.

  • Records and direction: which records to sync, with which filters, and whether data flows one way or both ways.

Validate what arrives before you write it. The OWASP API Security Top 10 lists skipping this step as a risk of its own: API10:2023 Unsafe Consumption of APIs.

SafeMode, a fleet safety platform, needed an integration for each new fleet client, because each new client brought different data sources and formats. DBB extracted the patterns common to those integrations into reusable templates and shared components, and established "consistent data transformation patterns" across client integrations, "regardless of source data format."

To check it, add a custom field in a test account and confirm it reaches your product through that connection's map, with no code change.

Planning your next integration?

Describe the integration you're adding and get a free project scope document with its key requirements, proposed architecture, delivery risks and a rough milestone plan.

Generate a free project scope document

Recover: Retries, Idempotency and Shared Rate Limits

Recovering safely means retrying only what a retry can fix, never applying a write twice, and keeping 1 customer's load and failures away from everyone else.

Retry Only Transient Errors, and Make Retried Writes Idempotent

Retry timeouts, 429 Too Many Requests and 5xx server errors with exponential backoff and jitter, and retry a write only if it can't apply twice. A 401 gets 1 token refresh and 1 retry. Never retry a 400 or any other error the same request will hit again.

Exponential backoff doubles the wait after each failed attempt, and jitter adds a random amount to it, so thousands of clients don't retry at the same moment. Honor a Retry-After header, which says how long to wait: RFC 6585 lets a provider send one with a 429. Cap the attempts too, because the AWS Builders' Library warns that retries during an overload "can make matters significantly worse".

A write is safe to retry when it's idempotent, meaning it applies once however many times the request arrives. Where a provider supports API idempotency, send an idempotency key with each write, usually in an Idempotency-Key header. The key is a unique value that lets the provider ignore a repeat. Stripe keeps a key for at least 24 hours and may remove it after that, so a retry has to land inside that window.

Where a provider has no idempotency keys, store your own ID for each record in a unique external-ID field and upsert on it, so the provider keeps 1 record per ID. An upsert is a single call that creates the record or updates the one already there. A search before each create is weaker, because 2 workers can both search, find nothing and both create the record.

Search can also lag behind writes: HubSpot's CRM search documentation notes that "It may take a few moments for newly created or updated CRM objects to appear in search results." Where search is all an API offers, send each record's writes through 1 worker at a time, and let reconciliation catch the duplicates that still get through.

Test both with a mock provider: a 429 with a Retry-After header should make the client wait at least that long, and a write sent twice with the same key should leave 1 record.

Give Each Customer Its Own Share of Rate Limits and Queues

Track rate limits and queues per customer connection, so 1 customer's first import or traffic spike can't slow every other customer's sync.

Some providers already count per customer: HubSpot gives public apps 110 requests every 10 seconds per installing account. Your own queue is where customers collide. Segment's 2018 write-up describes how a single shared queue let 1 slow destination hold up all the others.

  • First imports: size each new customer's first import against the quota, and run it at a lower priority than live syncs. A first import can drain a shared limit on its own. Some limits also make imports slow by design: since May 2025, Slack has allowed new installs of non-Marketplace apps 1 request a minute to its conversation history methods.

  • Dead-letter queue: a dead-letter queue holds events that still fail after their retries, so they stop blocking the queue and can be replayed after the fix. In DBB's payment integrations for a creator live-streaming app, "a message that kept failing went to that service's own dead-letter topic with its error attached, and the queue moved on."

The same rule holds when the provider is an AI model, where 1 customer's bulk job also runs up your bill. How to add AI to a SaaS product customers already rely on covers per-customer quotas and fallbacks for model calls.

To test it, start a large import for 1 test customer and watch another customer's syncs: they should stay on schedule.

Operate: Connection Monitoring and Provider Changes

Operating customer integrations means watching what each connection delivers and keeping up with what each provider changes.

Monitor Each Connection by Its Sync Results, and Show the Customer

Monitor each customer connection by the results of its recent syncs, not by whether a token is stored, and show the customer that same status.

Track these for every customer connection:

  • Last successful sync: when data last moved, which catches a connection that fails without an error.

  • Error rate: the share of calls that fail, which catches a connection that works for some calls and fails for others.

  • Token age: how close each token is to its provider's lifetime or idle limit.

  • Last provider response: the status code and error body of the most recent failure.

Show the customer the same view: connected, syncing or needs attention, with what failed and when. When the fix is theirs, such as a revoked grant or a missing permission, ask them to reconnect only that connection. When the fix is yours, tell them you're on it.

Decide who owns each alert before the first one fires. Support needs a short runbook that starts with the connection's last provider response. That response tells an expired token apart from a revoked grant, a missing permission or a rate limit, before anyone asks the customer to reconnect.

To check it, revoke a test connection at the provider: within 1 sync cycle, the customer's status should change and the alert should reach a named person.

Track Provider Changes Beyond the API Version

Track each provider's API versions, deprecation notices and policy changes, because a pinned API version doesn't protect you from new rate limits, token rules or app requirements.

Version schedules are the documented part: Shopify releases a new API version every quarter and supports each one for at least 12 months. A provider can also flag a deprecation in each response, with the Deprecation header defined in RFC 9745 (2025). Policy changes, such as Slack's 2025 history limit and the connection caps in Xero's pricing tiers from 2 March 2026, come with no version to pin.

  • Log the version of each call, so an upgrade shows up in your logs.

  • Alert on the Deprecation header, so a sunset reaches a person before it reaches a customer.

  • Validate response shapes against the fields you depend on, and alert when one disappears or changes type.

  • Name an owner for every provider, who reads its changelog and developer notices.

Verify: API Integration Testing Best Practices

Test how each API integration handles failures, using recorded provider responses so the tests stay fast and repeatable.

Sandboxes don't behave like production: Stripe's sandbox retries a failed webhook 3 times over a few hours, while live mode keeps retrying for up to 3 days. Recordings of real traffic fill that gap, and they're fast: Segment recorded real HTTP traffic and replayed it in tests, and the test suite for its 140+ destinations ran in milliseconds.

Automate the checks from each stage as one suite, and add the one they don't cover:

  • Revoked token: the connection shows as broken and stops calling the provider.

  • Duplicate and missing webhooks: your data is right after the next reconciliation run.

  • Exhausted quota: the client backs off, and other customers' syncs stay on time.

  • Forced upgrade: the suite passes against the provider's next API version before you switch.

You can also build a test provider into your product. For Doctify's enterprise sign-in, DBB set up OneLogin as a test identity provider. A switcher moves the platform between OneLogin and the production provider, "so QA can run the full sign-in flow without the client's live data."

Run these tests before each release and after every provider change, because either can break an integration that passed yesterday.

Disconnect: What Happens When a Customer Revokes Access

When a customer disconnects an integration or revokes access, stop processing for that connection and discard its credentials at once. Then decide what happens to the synced data, based on the provider's rules, your customer agreement, your retention policy and the type of data.

  • Stop processing: some providers send an event, and others signal only through a failing call. Slack sends the app_uninstalled and tokens_revoked events in no guaranteed order. Its tokens_revoked event lists user IDs, not tokens, so map those IDs back to your connections. If a provider rejects a refresh with invalid_grant, stop using the connection and check whether the customer revoked access or a rotated token was lost, before you treat it as a disconnect.

  • Discard credentials: delete the connection's tokens, and when the customer disconnects inside your product, revoke them at the provider as well. An uninstall at the provider can do that for you: Shopify's access token documentation says a merchant uninstalling your app "ends the access of all your app's tokens for that store."

  • Decide retention: we checked the docs of Google, Microsoft, Slack, HubSpot and Shopify, and of those, only Shopify sets an explicit rule. When a store uninstalls the app, Shopify's privacy compliance webhooks send shop/redact 48 hours later, asking the app to erase that store's data. Shopify gives the app 30 days to act and tells it not to redact data it's legally required to keep. For the other providers, the rule is yours to set.

To check it, disconnect a test customer: no job should call the provider for that connection again, no credential for it should remain, and each type of synced data should follow its written retention rule.

SaaS API Integration Checklist

Run this SaaS API integration checklist before each release and after every provider change.

Stage

Check

Pass when

Connect

Scopes and review

Every scope maps to a feature, and review time is on the launch plan

Connect

Token refresh

2 refreshes at once leave the connection working, and a token past its idle limit prompts a reconnect

Synchronize

Signatures

A changed body or an old timestamp is rejected

Synchronize

Duplicates

The same event sent twice at once is processed once

Synchronize

Missed events

Reconciliation fixes an event that never arrived

Synchronize

Field map

A new custom field arrives with no code change

Recover

Retries

A 429 makes the client wait; a 401 gets 1 refresh and 1 retry, then a reconnect prompt; a 400 is never retried

Recover

Idempotency

A retried write creates 1 record

Recover

Shared limits

1 customer's import leaves other customers' syncs on time

Operate

Status

A revoked connection shows as broken to the customer and alerts its owner within 1 sync cycle

Operate

Provider changes

Each provider has an owner, and logs show the API version of each call

Verify

Failure tests

Revocation, duplicate, quota and upgrade tests run before each release

Disconnect

Revocation and data

No calls and no credentials after a disconnect, and a retention rule for each type of data

First, fix the rows whose failures are silent or hit many customers at once: 1 refresh per connection at a time, signatures checked and events stored once, a fair share of limits for each customer, and a status built from sync results. The other rows protect you as you add customers and providers.

Planning a new integration, or fixing one that's failing? If you're planning the next one, generate a free project scope document to see its key requirements, proposed architecture and delivery risks before you build. If a customer integration is already failing, tell us what's breaking, and we'll reply within 1 business day.

FAQ

Markiian Reshetivskyi

Content Marketing Manager, Researcher