The SaaS Integration Migration Playbook: Switching Providers Without Downtime

If you are hitting scaling walls with Pipedream, an embedded iPaaS, or a legacy unified API, you need a highly structured strategy to extract your OAuth tokens, remap your data models, and swap the underlying infrastructure. Doing this wrong causes immediate data loss, broken webhooks, and the ultimate failure condition: forcing your enterprise customers to click "Reconnect" on their third-party accounts.

This guide provides the exact architectural steps to execute a zero-downtime provider switch. Whether you are graduating from a Pipedream prototype to a production-grade unified API or migrating between unified API providers, we cover how to extract your credentials, handle rate limits post-migration, and use declarative mappings to mimic your old API responses so your frontend code stays completely untouched.

Why Migrate from Pipedream to a Unified API

Teams migrate from Pipedream (or similar code-first workflow platforms) to a unified API when the operational cost of running N workflows for N providers starts to exceed the cost of adopting infrastructure designed for customer-facing integrations. The specific benefits:

1. Category coverage through one integration. A single GET /unified/crm/contacts call works for Salesforce, HubSpot, Pipedrive, Zoho, Close, and Copper. You stop maintaining separate workflows for every new provider a customer requests.
2. True white-label auth. Your own OAuth apps mean users see your brand during consent, not Pipedream's, which is often a hard requirement in enterprise security reviews.
3. Declarative per-customer customization. Custom fields, non-standard configurations, and enterprise edge cases become configuration overrides at the environment or account level rather than code branches inside workflow scripts.
4. Predictable operational surface. Standardized rate limit headers, uniform webhook payloads, and full request/response logs replace per-workflow debugging.
5. Portable connection state. When you own the OAuth client credentials, you can move tokens between infrastructures without forcing users to reconnect. That single fact determines whether a migration is a weekend project or a multi-quarter re-authentication campaign.

The rest of this guide is the operational playbook for making that migration a controlled event, not a fire drill.

The Hidden Costs of Integration Vendor Lock-In

Engineering leaders eventually realize that visual workflow builders or rigid API aggregators create massive technical debt as a product moves upmarket. Early-stage decisions optimize for speed. You use a platform that owns the OAuth application, forces you into their predefined data models, and silently swallows rate limit errors.

As your customer base grows, the operational reality changes. The 2025 State of SaaS Integration outlook reports that modern businesses rely on over 250 SaaS applications on average, creating a massive integration backlog for B2B SaaS vendors. Building a single integration in-house typically takes 8 to 12 weeks of engineering time.

To avoid building from scratch, teams adopt third-party integration tools. But if that tool is poorly architected, the maintenance burden simply shifts from building endpoints to debugging the vendor's black box. A 2025 Gartner analysis estimated that mid-market SaaS companies spend up to 24 percent of their engineering capacity just maintaining existing APIs.

Vendor lock-in occurs when the engineering time and operational cost required to rebuild on top of a vendor's proprietary model makes leaving too expensive. You are effectively held hostage by your own infrastructure. If you do not own the OAuth client credentials, you are locked into your provider. You cannot migrate tokens without forcing users to reconnect, which generates support tickets, introduces immediate churn risk, and burns social capital with your best accounts.

Escaping this trap requires transitioning to an architecture that separates your integration logic from your core business application, ensuring you retain ownership of the connection state.

Truto Integrations Platform vs Pipedream for Customer-Facing Integrations

If you are evaluating how to add integrations to your B2B product, you have likely encountered both Pipedream and unified API platforms. They solve related but fundamentally different problems, and understanding the distinction determines whether you prototype fast and migrate later - or adopt the right infrastructure from the start.

Pipedream is a developer workflow automation platform. It provides pre-built connectors for thousands of APIs, a visual workflow builder, and the ability to write custom Node.js or Python code at any step. Pipedream Connect, their customer-facing product, lets you embed integration workflows into your app so your end users can connect their own third-party accounts. It handles managed authentication and provides serverless compute to run your workflows.

A unified API is a single, normalized API interface that abstracts away the differences between providers in a specific category - CRM, HRIS, ATS, accounting. Instead of building separate integrations for Salesforce, HubSpot, and Pipedrive, you call one endpoint and get a consistent data model back. The unified API provider handles authentication, pagination, field mapping, and rate limit normalization across all supported integrations.

The architectural difference: Pipedream gives you tools to build each integration individually (faster than from scratch, but still one at a time). A unified API gives you coverage across an entire category through a single integration point.

One additional factor worth noting: Workday signed a definitive agreement to acquire Pipedream in November 2025, folding it into their AI agent platform alongside their Sana and Flowise acquisitions. For teams building long-term product integrations, this shifts Pipedream's roadmap toward Workday's enterprise AI ecosystem - which may or may not align with your needs.

When to Prototype on Pipedream

Pipedream is a strong choice when you need to validate demand before committing engineering resources:

• You have 1-3 customers requesting a specific integration and want to test whether the feature drives retention before building it natively.
• The integration is internal-facing (e.g., syncing your own CRM data to a dashboard) and does not need to scale across hundreds of customer accounts.
• You need a working prototype in days, not weeks, and are OK accepting Pipedream-branded auth flows and limited observability during validation.
• The integration is a one-off - a single customer needs a custom connection that will not become a product feature.

Pipedream's own case studies highlight this exact pattern - SaaS companies using the platform to prototype integrations for a few customers before investing in a native build. That is a perfectly valid use of the platform.

When to Commit to a Unified API

You should skip the prototype phase and adopt a unified API directly when:

• Integrations are a core product feature, not a nice-to-have. If your sales team loses deals because you lack a Salesforce integration, you need production-grade infrastructure from day one.
• You need to support 5+ providers in the same category. Building and maintaining individual Pipedream workflows for Salesforce, HubSpot, Pipedrive, Zoho, Close, and Copper is a linear scaling problem. A unified API collapses this to one integration.
• Enterprise customers require white-label experiences. Pipedream's auth flows display Pipedream branding and ask users to consent to Pipedream's data access, which enterprise buyers will flag during security reviews.
• Per-customer customization is a requirement. When Customer A has custom Salesforce fields and Customer B uses a non-standard HubSpot configuration, you need declarative per-account overrides - not code branches in workflow scripts.
• You need full observability in production. Debugging a failed sync at 2 AM requires complete request/response logs for every external API call, not partial workflow execution traces.

For most B2B SaaS teams moving upmarket, the inflection point arrives when integrations shift from "feature request" to "deal blocker." At that point, the cost of migrating off a prototype platform exceeds the cost of adopting the right infrastructure early.

When to Add a Detailed Migration Playbook for Switching Providers

Recognizing the need to migrate is the first step. You should begin drafting a SaaS vendor migration playbook when your engineering team spends more time fighting your integration provider than shipping core features.

Signs you need to execute a migration:

• The Re-Authentication Cliff: Your provider routinely drops OAuth connections, and because they own the client ID, you have no access to the raw refresh tokens to debug the failure.
• Silent Rate Limiting: The provider throttles your requests internally without passing standard HTTP 429 headers, causing asynchronous jobs to fail unpredictably.
• Data Model Rigidity: Your enterprise customers use highly customized Salesforce or NetSuite instances, and your provider's "unified" model drops custom fields or fails to map polymorphic relationships.
• Missing Endpoints: A customer requests an obscure endpoint (e.g., a specific custom object in HubSpot), and your provider tells you it will take six months to add it to their roadmap.

If you are experiencing these bottlenecks, you need to execute a structured cutover. For teams moving off visual builders, review our Migration Playbook: From Make.com Prototypes to Native SaaS Integrations to understand the architectural shift from graph-based logic to native execution.

Pre-Migration Discovery and Checklist

Before you write a line of migration code, you need a complete inventory of what you have and what you own. Skipping this step is the primary reason migrations slip by months.

Inventory your active integrations. For each customer-facing integration currently running on Pipedream:

• Provider name (Salesforce, HubSpot, Jira, etc.)
• Number of connected customer accounts
• Which resources are read (contacts, deals, tickets, employees)
• Which resources are written back
• Trigger model: polling schedule, webhook-driven, or user-initiated
• Peak throughput per hour and largest response payload seen in production

Audit OAuth app ownership. For every provider, verify who registered the OAuth application:

• If you registered the app in the provider's developer console and hold the client ID/secret, you can move tokens.
• If Pipedream registered the app (Pipedream Connect managed auth), the refresh tokens are bound to Pipedream's client ID and cannot be reused. Every user must re-authenticate.

This single audit determines whether Phase 1 (token hot-swap) is possible for each provider. If OAuth ownership is mixed across your portfolio, plan two migration tracks: hot-swap for owned apps, coordinated re-auth for the rest.

Catalog your current response contracts. Whatever shape your frontend and backend consume today becomes the target for the mapping layer in Phase 2. Export sample payloads for every resource and every provider. If you have per-customer field mappings baked into workflow scripts, extract those into a spreadsheet before touching the migration.

Map cross-system dependencies. List every downstream consumer of the current integration: sync jobs that read the data, webhook receivers that trigger internal workflows, dashboards that render it, and reports that aggregate it. Each of these must be validated during the parallel-run phase.

Confirm rate limit budgets with upstream providers. Many providers issue rate limits per OAuth app, not per user. When you switch to your own OAuth app, you inherit a fresh budget - but you also lose whatever elevated limits Pipedream negotiated. Confirm the default limits and file for increases early where needed.

Pre-Migration Discovery Checklist:

• Full inventory of active integrations with resource-level detail
• OAuth ownership confirmed for every provider (BYO vs Pipedream-owned)
• Sample payloads exported for every resource in production shape
• Per-customer customizations extracted into a mapping catalog
• Downstream consumers documented (sync jobs, webhooks, dashboards)
• Rate limit ceilings confirmed with each upstream provider
• Success criteria and rollback triggers defined with the product team

Architecture: Before and After

The architectural shift you are executing is from N workflows per category to one unified interface. The before state has your application talking to a fan of provider-specific workflows, each with its own code path and its own mapping logic.

flowchart LR
    A["Your App"] --> W1["HubSpot Workflow<br>(custom code)"]
    A --> W2["Salesforce Workflow<br>(custom code)"]
    A --> W3["Pipedrive Workflow<br>(custom code)"]
    A --> W4["Zoho Workflow<br>(custom code)"]
    W1 --> P1["HubSpot API"]
    W2 --> P2["Salesforce API"]
    W3 --> P3["Pipedrive API"]
    W4 --> P4["Zoho API"]

The after state collapses the fan into a single unified endpoint. A generic execution engine reads declarative configuration to route each request to the correct provider and transform the response into your canonical shape.

flowchart LR
    A["Your App"] --> U["GET /unified/crm/contacts"]
    U --> E["Generic Execution Engine<br>(config + JSONata)"]
    E --> P1["HubSpot API"]
    E --> P2["Salesforce API"]
    E --> P3["Pipedrive API"]
    E --> P4["Zoho API"]

The same code path handles every provider. Adding a new provider is a configuration change, not a code deployment.

Phase 1: The OAuth Token Extraction and Hot-Swap

The highest risk in any infrastructure migration is the credential state. If you lose the active OAuth tokens, your integration breaks.

To execute a zero-downtime migration, you must employ the Bring Your Own (BYO) OAuth Client pattern. If you own the OAuth app in the provider's developer console (e.g., you created the app in Salesforce and hold the Client ID and Client Secret), you can move the tokens. If your legacy provider forces you to use their white-labeled OAuth app, you are out of luck and must ask users to re-authenticate.

Assuming you own the app, the token extraction and hot-swap follows a strict sequence.

sequenceDiagram
    participant DB as Legacy Provider Vault
    participant Script as Migration Script
    participant Truto as Truto Credential Store
    participant API as Upstream SaaS (e.g., Salesforce)

    Script->>DB: Export active Access & Refresh Tokens
    DB-->>Script: Return encrypted token payloads
    Script->>Truto: Import tokens via Management API
    Note over Truto: Store tokens against<br>new Integrated Account ID
    Truto->>API: Execute test call using imported token
    API-->>Truto: HTTP 200 OK
    Note over Script: Token state successfully migrated

When you export tokens from your legacy provider, you must capture the access_token, the refresh_token, and the exact expires_at timestamp.

OAuth token refresh flows are highly susceptible to concurrency issues. If your old provider and your new provider attempt to refresh the same token simultaneously, the upstream API will likely issue an invalid_grant error, revoking all access.

To prevent this, you must pause all background syncs on the legacy provider before importing the tokens into the new system. Once imported, the new system takes over the token lifecycle. Truto refreshes OAuth tokens shortly before they expire, using per-account locking to prevent concurrent refresh races. For a highly specific example of this process, read How to Create an Apideck-to-Truto Migration Guide or our broader piece on OAuth App Ownership Explained.

Phase 2: Mapping the Unified Data Models

Most unified API platforms solve API differences with brute force. Behind their facade, they maintain separate code paths for each integration - if (provider === 'hubspot') { ... } else if (provider === 'salesforce') { ... }. They have integration-specific database columns and hardcoded business logic.

When you migrate away from these platforms, your frontend and backend systems are still expecting data in that specific, rigid format. Changing your internal application logic to handle a new data shape is risky and time-consuming.

Instead of rewriting your application, use a declarative transformation layer to mimic the legacy provider's response. Truto's architecture contains zero integration-specific code. Integration behavior is defined entirely as data using JSONata expressions.

Pipedream Workflow vs Truto Unified API Call

The practical difference shows up immediately when you compare the code your app has to run today (per provider) against a single unified call.

Before: Pipedream, HubSpot workflow step

// Provider-specific workflow #1: HubSpot
export default defineComponent({
  props: { hubspot: { type: "app", app: "hubspot" } },
  async run({ $ }) {
    const res = await axios($, {
      url: "https://api.hubapi.com/crm/v3/objects/contacts",
      headers: {
        Authorization: `Bearer ${this.hubspot.$auth.oauth_access_token}`,
      },
      params: { properties: "firstname,lastname,email", limit: 100 },
    })
    // Manually reshape into your app's canonical contact
    return res.results.map((r) => ({
      id: r.id,
      first_name: r.properties.firstname,
      last_name: r.properties.lastname,
      email: r.properties.email,
    }))
  },
})

Before: Pipedream, Salesforce workflow step (completely separate code)

// Provider-specific workflow #2: Salesforce
export default defineComponent({
  props: { salesforce: { type: "app", app: "salesforce_rest_api" } },
  async run({ $ }) {
    const soql = "SELECT Id, FirstName, LastName, Email FROM Contact LIMIT 100"
    const res = await axios($, {
      url: `${this.salesforce.$auth.instance_url}/services/data/v59.0/query?q=${encodeURIComponent(soql)}`,
      headers: {
        Authorization: `Bearer ${this.salesforce.$auth.oauth_access_token}`,
      },
    })
    return res.records.map((r) => ({
      id: r.Id,
      first_name: r.FirstName,
      last_name: r.LastName,
      email: r.Email,
    }))
  },
})

Every new provider means a new file, new auth wiring, and a new mapping block. Bugs get fixed once per workflow.

After: Truto unified API call (one call, every CRM provider)

const res = await fetch(
  `https://api.truto.one/unified/crm/contacts?integrated_account_id=${accountId}&limit=100`,
  { headers: { Authorization: `Bearer ${TRUTO_API_TOKEN}` } }
)
const { result } = await res.json()
// result is already normalized across HubSpot, Salesforce, Pipedrive, Zoho, Close:
// [{
//   id: "123",
//   first_name: "John",
//   last_name: "Doe",
//   email_addresses: [{ email: "john@example.com", is_primary: true }],
//   remote_data: { ...original API response preserved... }
// }]

The caller does not need to know whether accountId belongs to a HubSpot or Salesforce tenant. The same request path handles both. The original API response is preserved on remote_data so you can still access provider-specific fields when needed.

Mimicking Your Legacy Response Shape

If your app already consumes a specific response shape from a previous provider (Merge, Apideck, or a bespoke internal contract), you do not want to touch your frontend or backend code during the cutover. Push the transformation into a declarative mapping so the endpoint returns the exact JSON your app already parses.

// Example JSONata mapping to mimic a legacy unified CRM response
{
  "id": $.id,
  "legacy_unified_format": {
    "first_name": $.properties.firstname,
    "last_name": $.properties.lastname,
    "email_addresses": [
      {
        "email": $.properties.email,
        "type": "work"
      }
    ],
    "custom_fields": $.properties.custom_enterprise_identifier
  }
}

By pushing the transformation logic to the mapping layer via JSONata, your core application remains unaware that the underlying infrastructure has changed. The endpoints return the exact same JSON schema your frontend expects.

If you encounter an edge case where the unified model simply cannot represent the data you need, you should fall back to a Proxy API. A Proxy API allows you to bypass the unified model entirely and make raw, authenticated REST calls directly to the underlying provider (e.g., hitting the NetSuite SuiteQL endpoint directly) while the platform handles the authentication headers automatically.

Phase 3: Handling Rate Limits and Webhooks Post-Migration

Operational realities surface immediately after the cutover. The two most common failure points are unhandled rate limits and malformed webhook payloads.

Transparent Rate Limiting

Many legacy integration platforms attempt to hide rate limits by silently queueing and delaying requests. This creates unpredictable latency and makes debugging impossible.

Instead of silent throttling, Truto normalizes upstream rate limit information into standardized headers per the IETF specification. Regardless of whether you are calling Jira, Salesforce, or QuickBooks, you will receive consistent headers:

• ratelimit-limit: The maximum number of requests permitted in the current window.
• ratelimit-remaining: The number of requests remaining in the current window.
• ratelimit-reset: The time at which the current rate limit window resets.

The calling application is entirely responsible for implementing retry logic. You must build an exponential backoff algorithm in your worker queues that reads the ratelimit-reset header and pauses execution until the window clears. This explicit contract prevents silent failures and gives your engineering team full control over queue priority.

Webhook Normalization and Delivery

Third-party webhooks are notoriously difficult to standardize. Providers use different signature verification methods, different payload structures, and different retry policies.

Truto supports two inbound webhook ingestion patterns: account-specific and environment-integration fan-out. When an event arrives from a provider, Truto uses JSONata-based configuration for provider-specific event normalization.

Outbound delivery to your customer endpoints uses signed payloads with alarm-driven retries. Because normalized payloads can exceed standard HTTP size limits, large payloads are written to object storage, and a reference is sent to your endpoint.

You must verify the X-Truto-Signature header on every incoming request to ensure the event actually originated from your new infrastructure and was not spoofed.

Phase 4: The Silent Cutover and Deprecation

The final phase is routing traffic to the new infrastructure without causing a disruption. Never execute a "big bang" cutover where you flip all read and write traffic simultaneously.

Step 1: Dark Reads. Route a percentage of your read requests (e.g., fetching a list of contacts) through the new infrastructure while continuing to serve the application from the legacy provider. Log the responses from both systems and diff them asynchronously. If the JSONata mappings from Phase 2 are correct, the diffs will be identical.

Step 2: Write Traffic Cutover. Once the read diffs are clean, begin routing write operations through the new infrastructure. Monitor your API logs closely for HTTP 400 validation errors or HTTP 429 rate limits. Because you implemented the IETF rate limit headers in Phase 3, your queues should gracefully back off if the upstream provider is saturated.

Step 3: Deprecation. Once 100 percent of traffic is flowing through the new infrastructure and the OAuth tokens are successfully refreshing, you can safely spin down the legacy provider.

By treating integrations as declarative data rather than hardcoded logic, and by retaining absolute ownership over your OAuth clients, you eliminate the threat of vendor lock-in. For a deeper understanding of the operational costs of maintaining these systems, review The SaaS Product Manager's Integration Rollout Playbook.

Testing and Rollout Best Practices

A migration that passes unit tests in staging can still fail on real customer data. Your rollout plan needs to catch the edge cases production traffic will expose.

Shadow the new infrastructure with real traffic. Before any customer-facing switch, mirror a percentage of production reads to the new API and compare responses against the legacy provider offline. Diff by field, not by string match, since minor ordering differences in arrays are expected. Track a fidelity score per resource per provider and hold cutover until it exceeds an agreed threshold (typically 99.5 percent on non-null fields).

Use a feature flag per customer, not per environment. A per-customer flag lets you cut over one tenant at a time, starting with internal test accounts, then friendly design partners, then general availability. If a customer-specific mapping bug surfaces, you flip only that customer back to the legacy path while you fix the mapping override.

Test with the messiest customer accounts first. The enterprise customer with 400 Salesforce custom fields and a non-standard territory model will find bugs that your synthetic test data never will. Identify these accounts during discovery and prioritize them in the parallel-run cohort.

Verify write idempotency during the parallel run. If your dark reads accidentally turn into dark writes (a common mistake when a mapping generates a POST instead of a GET), you will double-create records. Add an idempotency key to every write and confirm the upstream provider deduplicates correctly.

Validate webhook delivery end to end. Trigger a create, update, and delete event for each resource from the upstream provider and confirm it reaches your receiver with a valid signature, the expected schema, and the correct timing. Do this per provider - each one has its own webhook quirks.

Run a load test at 2x expected peak. Rate limits, connection pool exhaustion, and token refresh contention often only surface under sustained load. Simulate a full sync across your top 20 accounts running concurrently before cutover.

Define rollback triggers before you flip the switch. Write down the specific error rate, latency, or auth-failure thresholds that will cause you to roll back. Publish them to the on-call channel. Anyone should be able to execute a rollback without a meeting.

Migration Paths: Estimated Engineering Effort and Timeline

Whether you prototyped on Pipedream or are migrating off another integration provider, the engineering effort depends on your current architecture and how many active integrations you are running. Here are realistic timelines assuming a team of 2-3 engineers working full-time on the migration.

Path A: Pipedream Prototype to Unified API

If you built customer-facing integrations using Pipedream Connect and need to migrate to a unified API for scale, white-labeling, or multi-tenant support.

Total estimated timeline: 6-10 weeks with 2-3 dedicated engineers. The primary variable is the number of active integrations and the complexity of your per-customer customizations.

Per-connector cost: A typical CRM or HRIS connector already covered by the unified model migrates in 2-4 engineer-days end to end - most of which is testing against real customer data, not writing new code. Connectors that need custom endpoints (a bespoke Salesforce object, a rarely-used HubSpot endpoint) add roughly 1-3 additional days each for configuration and mapping.

Path B: Direct Unified API Adoption (No Migration)

If you are building integrations for the first time and choosing between Pipedream and a unified API.

Total estimated timeline: 3-5 weeks with 1-2 engineers. Because the unified API handles provider-specific differences, you are building one integration, not N.

The difference in effort between the two paths illustrates the core trade-off: prototyping on Pipedream gets you to a demo faster, but the migration tax is real. If you know integrations will be a core product capability, Path B avoids the rework entirely.

Common Pitfalls and How to Remediate Them

Even with a disciplined plan, specific failure modes recur across almost every migration. Anticipate them:

Pitfall 1: Custom fields silently disappear. Legacy unified providers often normalize only the fields defined in their base schema and drop everything else. When you migrate, customers notice the moment their custom enterprise_account_id field is missing.

Remediation: Use per-account mapping overrides so each customer's custom fields are added to the unified response for their tenant only. Preserve remote_data (the raw provider response) alongside the normalized payload so nothing is ever truly lost.

Pitfall 2: Refresh token races on cutover day. If both the legacy provider and the new provider try to refresh the same OAuth token in overlapping windows, the upstream API revokes the token and every downstream call fails with invalid_grant.

Remediation: Fully pause the legacy provider's sync jobs and webhook consumers before importing tokens into the new platform. Do not resume anything on the legacy side, even for observability, until the migration completes.

Pitfall 3: Silent rate limit throttling in the legacy platform hides real usage. If Pipedream (or your previous provider) queues and retries requests internally, you never see the true request rate hitting the upstream API. When you cut over, you suddenly hit real 429s that were previously invisible.

Remediation: During the parallel run, instrument the new platform's ratelimit-remaining header per account. Build the exponential backoff logic against ratelimit-reset before cutover, not after.

Pitfall 4: OAuth scopes mismatch between old and new apps. Your legacy provider may have requested a broader scope than what your new OAuth app requests, so tokens imported from the old system fail on endpoints that require the missing scope.

Remediation: Diff the scope lists between the two OAuth apps before importing tokens. Either widen the new app's scope to match, or plan a coordinated re-consent flow for customers whose tokens are missing scopes.

Pitfall 5: Webhook signature mismatch after cutover. Your existing webhook receivers verify signatures against the legacy provider's HMAC scheme. The new platform uses a different signature format, and every incoming event fails verification.

Remediation: Update the receiver to verify the new platform's X-Truto-Signature header before cutover. Run both verification paths in parallel during the shadow window so no event is dropped.

Pitfall 6: Pagination cursors change format. Providers like HubSpot use opaque cursors that mean nothing outside the provider's own context. If your legacy platform re-encoded them and your new platform passes them through raw, any stored cursors from mid-sync jobs become invalid.

Remediation: Complete or discard all in-flight paginated jobs before cutover. Do not attempt to carry pagination state across the provider boundary.

Pitfall 7: Enterprise IP allowlisting breaks. Customers who allowlisted the legacy provider's IP ranges will reject connections from the new platform's egress IPs.

Remediation: Identify allowlisted accounts during discovery. Coordinate the IP-list change with each customer's security team on a schedule that lines up with their cutover window. Use static egress proxies where the new platform supports them.

Pitfall 8: Log volume overwhelms the new platform's dashboard. You are used to sparse logs from a workflow platform. The new unified API logs every request/response - which is what you wanted, but the volume can catch operators off guard.

Remediation: Configure log forwarding to your existing observability stack (Datadog, Splunk, or similar) from day one so alerts and dashboards you already know how to read cover the new platform.

Operational Migration Checklist

Use this checklist to track progress across the four critical migration workstreams. Each item should have a clear owner and a verified completion date before you begin the cutover described in Phase 4.

Authentication and Credentials

• Confirm you own the OAuth client ID and secret for every provider
• Export access tokens, refresh tokens, and expiry timestamps from the legacy platform
• Pause all background syncs on the legacy provider before importing tokens
• Import tokens into the new platform and verify with a test API call per account
• Confirm token refresh cycle is working - monitor for invalid_grant errors over 48 hours

Data Model Mapping

• Document the legacy provider's response schema for every resource you consume
• Create declarative mappings that replicate the legacy response shape
• Validate mappings against production data from at least 5 customer accounts
• Handle edge cases: null fields, polymorphic relationships, custom fields, multi-select enums
• Verify pagination behavior matches (cursor format, page sizes, sort order)

Background Jobs and Sync

• Inventory all scheduled syncs, polling jobs, and triggered workflows on the legacy platform
• Recreate each job against the new infrastructure's API
• Implement idempotency keys to prevent duplicate processing during the parallel-run phase
• Verify webhook receivers accept the new platform's payload format and signature scheme
• Test webhook delivery with at least one create, update, and delete event per resource

Monitoring and Observability

• Set up alerts for HTTP 429 (rate limit) responses from upstream providers
• Set up alerts for HTTP 401/403 (auth failure) responses indicating token expiry or revocation
• Monitor response latency P50/P95 across all integration endpoints
• Verify that full request/response logs are available for debugging in production
• Create a dashboard tracking error rates per provider, per customer account
• Establish an on-call runbook for common failure modes (token revocation, rate limiting, provider outage)