Heroku Salesforce Integration

Heroku ↔ Salesforce Integration

Heroku and Salesforce share an owner (Salesforce, Inc.) and that's reflected in the integration surface — there are six well-defined paths, each tuned to a different shape of problem. Picking wrong is the same shape of cost as it is on the AWS side: a custom Apex callout where Heroku Connect would have synced, or Connect when the team really needed AppLink's API exposure into Flow.

This skill is the decision layer for Heroku-specific paths. AWS has its own decision skill (integration/aws-salesforce-patterns); MuleSoft has its own.

Before Starting

• Confirm the direction. Heroku Connect is bidirectional but Postgres-centric. AppLink exposes Heroku APIs into Salesforce. External Objects virtualizes Postgres data into Salesforce without copy.
• Confirm the plan tier. Demo Heroku Connect caps at 10,000 synced rows and 10-minute minimum polling — fine for a proof of concept, never for production. Enterprise / Shield have flexible polling and unlimited (per contract) row counts.
• Confirm region co-location. Heroku Connect's wall-clock latency is dominated by the network round-trip between the Heroku Postgres region, the Connect add-on region, and the Salesforce org's instance region. Mismatched regions can multiply sync lag by 2–3×.
• Decide whether the integration user is an integration-only Salesforce user (recommended) or a real human's account (problematic — query limits per user, password rotation breaks the OAuth tie).

Core Concepts

The six Heroku integration paths

1. Heroku Connect — managed bidirectional sync between Salesforce SObjects and Heroku Postgres tables. OAuth-based; uses an integration Salesforce user. Right when the Heroku app needs a local database copy of Salesforce data, or when both sides own different parts of the truth and need eventual-consistency sync.
2. Heroku AppLink — newer (2024+) feature that exposes a Heroku-hosted API as a first-class service inside Salesforce, callable from Flow, Apex, Data Cloud, and Agentforce. Right when Salesforce-side users / agents need to invoke Heroku-side business logic without an Apex callout class.
3. Heroku External Objects (Salesforce Connect with oData) — Heroku Postgres tables surface in Salesforce as External Objects via an oData wrapper. Read or read-write. Right when Salesforce users want to view / search / report on Heroku data without copying it.
4. Salesforce Platform Events → Heroku — Heroku app subscribes to Salesforce Pub/Sub or CometD streaming. Right for event-driven Heroku reaction to Salesforce changes; lower-overhead than Connect for pure event flow.
5. Heroku → Salesforce REST API — Heroku app calls Salesforce REST endpoints directly using OAuth (Connected App, JWT bearer flow). Right for one-shot operations the Heroku side initiates — approvals, metadata reads, custom Apex REST endpoints.
6. Salesforce Apex / Workflow → Heroku REST — Apex callout via Named Credential to a Heroku app endpoint. Right for synchronous Salesforce-initiated calls into Heroku logic; same caveat as Apex callouts to Lambda — governor limits apply.

Plus a separate UI option: Salesforce Canvas embeds a Heroku web app inside the Salesforce UI (App Launcher, Service Console, Lightning page). Canvas is not Heroku-specific — any web app can be a Canvas app — but Heroku is a common host because of how easy the Connected App + Heroku app pairing is to wire.

Heroku Connect mechanics

Salesforce Canvas: Signed Request vs OAuth Web Server Flow

Canvas has two auth models — Salesforce (the embedding container) signals to the Heroku app (the embedded UI) which user is logged in.

• Signed Request (default) — Salesforce POSTs a signed payload to the Heroku app when the user opens the Canvas app. No consent screen. The signed payload includes the user context, an OAuth token, and Salesforce instance URL. Right for embedded UIs where the user has already authenticated to Salesforce.
• OAuth 2.0 Web Server Flow — The Canvas app initiates a normal OAuth dance, including the Salesforce consent screen. Right for apps that also run outside the Canvas frame and need their own user identity.

Recommend Signed Request for any embedded-only Canvas app; OAuth for hybrid (embedded + standalone) apps.

Decision Guidance

Common Patterns

Pattern A — Heroku app with local Postgres mirror

When to use. A Heroku web app whose business logic is database-heavy (joins, aggregates, full-text search) and whose source of truth lives in Salesforce.

How it works. Heroku Connect add-on provisions on top of Heroku Postgres. Configure object mappings in the Connect dashboard (Salesforce → Postgres read-only, or bidirectional). Use a dedicated Salesforce integration user with API Enabled + View All + Modify All. Region-align Heroku Postgres, Connect, and Salesforce.

Why not the alternative. A custom polling job hitting Salesforce REST API has zero managed retry, no trigger-log replay, and no easy way to write back. Connect is the managed equivalent.

Pattern B — Heroku-hosted API exposed to Flow / Agentforce

When to use. A Python / Node service does ML scoring, document parsing, or any computation Apex isn't suited for, and a Salesforce admin / agent needs to invoke it from a Flow or Agentforce action.

How it works. Configure Heroku AppLink on the Heroku app. Salesforce admins discover the exposed actions in Setup → External Services / Flow Builder; agents discover them as registered tools. No Apex callout class needed; auth + parameter shape is handled by AppLink.

Why not the alternative. Writing an Apex @InvocableMethod wrapper around an HTTP callout works but adds a code maintenance surface for something the platform handles natively now.

Pattern C — Virtualized Heroku Postgres data inside Salesforce

When to use. Heroku is the system-of-truth for some transactional data (orders, sessions, telemetry) and Salesforce users need to view / search / report on it from a Lightning record page.

How it works. Heroku External Objects exposes Postgres tables as oData endpoints; Salesforce Connect consumes them as External Objects. The data stays in Postgres; Salesforce queries it on demand.

Why not the alternative. Heroku Connect copies the data into Salesforce storage (data + index costs). External Objects is read-mostly virtualization — no storage cost, but join + filter performance is bounded by oData round trips.

Recommended Workflow

1. State the integration in one sentence. Direction, latency, volume, where the source of truth lives.
2. Walk the Decision Guidance table. First match wins. If two rows match, the more specific one (volume / latency) takes precedence.
3. Choose plan tier. Demo = POC only; Enterprise / Shield = production. The 10K-row cap on demo is the most common surprise.
4. Set up the integration Salesforce user. One per Heroku Connect add-on; API Enabled + View All + Modify All. Document the rotation cadence in your runbook.
5. Co-locate regions. Heroku Postgres, Connect add-on, Salesforce instance. Mismatched regions are the #1 latency surprise.
6. For Canvas: Signed Request first. OAuth Web Server Flow only if the app also lives outside Salesforce.

Review Checklist

• Decision: which of the six paths, with one sentence justifying it against the alternatives.
• Plan tier explicit (demo vs Enterprise vs Shield).
• Integration user is dedicated to the Heroku Connect add-on (not shared with other integrations).
• Salesforce integration user has View All (large-query performance depends on it).
• Heroku Postgres / Connect / Salesforce regions are co-located.
• If Canvas: Signed Request unless explicit reason for OAuth.
• If Connect: trigger-log retention matches recovery SLO (7d demo, 31d Enterprise).
• No Postgres connection pooling on the Connect-attached database.

Salesforce-Specific Gotchas

1. Demo plan caps at 10,000 rows. Hit silently — sync stops; status dashboard shows the cap. Plan for Enterprise / Shield before going to production. (Source: Heroku Connect docs)
2. One integration user per add-on. Salesforce caps concurrent queries (10) and active OAuth tokens (5) per user. Sharing a user across add-ons causes throttling. (See references/gotchas.md § 2.)
3. Re-authenticating Connect to a different org is not supported. Sandbox refresh requires recreating the Connect connection from scratch. (See references/gotchas.md § 3.)
4. Postgres connection pooling breaks Connect. Use direct connections from your Heroku app dyno. (See references/gotchas.md § 4.)
5. OPERATION_TOO_LARGE on Connect's Salesforce queries when the integration user lacks View All. The error doesn't name the missing permission; it surfaces as a generic large-query failure. (See references/gotchas.md § 5.)
6. Canvas Signed Request and OAuth Web Server Flow are not interchangeable. Mixing them (signing then re-running OAuth) creates a confused-deputy situation. (See references/gotchas.md § 6.)

Output Artifacts

Related Skills

• integration/aws-salesforce-patterns — sibling skill for the AWS path; same decision-matrix shape.
• integration/event-relay-configuration — Pub/Sub → EventBridge for AWS; for Heroku-side Pub/Sub subscribers the same Pub/Sub API is the entry point.
• architect/hybrid-integration-architecture — broader topology decisions; consult before picking a Heroku path if AWS, MuleSoft, or self-hosted are also options.
• standards/decision-trees/integration-pattern-selection.md — the master integration decision tree; Heroku is one branch.