Home / integration / heroku-salesforce-integration

heroku-salesforce-integration

Heroku ↔ Salesforce integration paths — Heroku Connect (Postgres bidirectional sync), Heroku AppLink (expose Heroku APIs to Flow / Apex / Agentforce), Heroku External Objects (Salesforce Connect oData), Platform Events, REST API in either direction, and Salesforce Canvas for UI. NOT for AWS integration — use integration/aws-salesforce-patterns.

v1.0.1
Salesforce Spring '25+
Updated 2026-08-14
Reliability
Security
Operational Excellence

heroku
heroku-connect
heroku-applink
salesforce-connect
canvas
postgres
integration-pattern

Open the skill folder on GitHub

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

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.
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.
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.
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.
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.
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

Aspect	Detail
Auth	One Salesforce integration user per add-on. Distinct users for distinct add-ons (concurrent-query and token caps are per user).
Sync model	Trigger-based on the Postgres side (writes Postgres → Salesforce via the trigger log); polling on the Salesforce side (reads Salesforce → Postgres on the polling cadence).
Plan tiers (2026)	Demo: 10K rows, 10-minute polling, 7-day trigger log. Enterprise / Shield: per-contract row counts, configurable polling, 31-day trigger log.
Required permissions	`API Enabled`, `View All`, `Modify All`. Without `View All`, large queries can throw `OPERATION_TOO_LARGE`.
Not supported	Postgres connection pooling (use direct connections), `postgres_fdw`, Heroku review-app `app.json` add-on provisioning.

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

Situation	Recommended Approach	Reason
Heroku app needs a local Postgres copy of Account / Contact / Custom Objects	Heroku Connect	Managed bidirectional sync; eventual consistency
Salesforce Flow needs to call a Python ML scoring service hosted on Heroku	Heroku AppLink	Exposes the API as a Flow-native action, no Apex callout class
Salesforce users want to search / report on Heroku transactional data without copying	Heroku External Objects	Salesforce Connect (oData) virtualizes the tables
Heroku service must react to Salesforce record changes within seconds	Platform Events → Heroku subscriber (Pub/Sub API)	Lower overhead than Connect for pure event flow
Heroku app needs occasional Salesforce data — not a continuous mirror	Heroku → Salesforce REST API with JWT bearer flow	No add-on, just OAuth
Salesforce trigger needs synchronous data from a Heroku microservice	Apex callout via Named Credential	Same governors as any callout — bulkify
Embed a Heroku UI inside Salesforce for end users	Canvas (Signed Request)	Default auth; no consent prompt
Demo / proof-of-concept: 1,000 records, daily check-ins	Heroku Connect demo plan	Free, 10K-row cap, 10-min polling — fine for POC
Production: 1M+ rows, sub-minute lag	Heroku Connect Enterprise / Shield	Demo plan cannot meet production SLAs
Cross-org integration where Heroku is just a passthrough	Probably none of these — use a direct Salesforce → Salesforce path or MuleSoft	Heroku adds latency without buying you anything

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

State the integration in one sentence. Direction, latency, volume, where the source of truth lives.
Walk the Decision Guidance table. First match wins. If two rows match, the more specific one (volume / latency) takes precedence.
Choose plan tier. Demo = POC only; Enterprise / Shield = production. The 10K-row cap on demo is the most common surprise.
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.
Co-locate regions. Heroku Postgres, Connect add-on, Salesforce instance. Mismatched regions are the #1 latency surprise.
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

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)
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.)
Re-authenticating Connect to a different org is not supported. Sandbox refresh requires recreating the Connect connection from scratch. (See references/gotchas.md § 3.)
Postgres connection pooling breaks Connect. Use direct connections from your Heroku app dyno. (See references/gotchas.md § 4.)
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.)
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

Artifact	Description
Decision recommendation	One paragraph naming the chosen path, plan tier, integration user model, and region.
Connection runbook	Integration user provisioning, plan tier procurement, region pinning, OAuth refresh cadence.
Risk register	Limits the design will get within 50 % of (row count, polling cadence, region latency) plus mitigation.

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.