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
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. |
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.
1---2name: heroku-salesforce-integration3description: 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 embedding. Decision matrix + Heroku Connect deep dive (OAuth integration user, plan-tier row limits, polling cadence, region co-location). NOT for AWS integration (see integration/aws-salesforce-patterns), NOT for generic PaaS, NOT for MuleSoft.4---5
6# Heroku ↔ Salesforce Integration
7
8Heroku and Salesforce share an owner (Salesforce, Inc.) and that's reflected
9in the integration surface — there are six well-defined paths, each tuned to
10a different shape of problem. Picking wrong is the same shape of cost as it
11is on the AWS side: a custom Apex callout where Heroku Connect would have
12synced, or Connect when the team really needed AppLink's API exposure into
13Flow.
14
15This skill is the **decision layer** for Heroku-specific paths. AWS has its
16own decision skill (`integration/aws-salesforce-patterns`); MuleSoft has its
17own.
18
19---
20
21## Before Starting
22
23- 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.
24- 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.
25- 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×.
26- 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).
27
28---
29
30## Core Concepts
31
32### The six Heroku integration paths
33
341. **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.*
352. **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.*
363. **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.*
374. **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.*
385. **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.*
396. **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.*
40
41Plus 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.
42
43### Heroku Connect mechanics
44
45| Aspect | Detail |
46|---|---|
47| Auth | One Salesforce integration user per add-on. Distinct users for distinct add-ons (concurrent-query and token caps are *per user*). |
48| 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). |
49| 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. |
50| Required permissions | `API Enabled`, `View All`, `Modify All`. Without `View All`, large queries can throw `OPERATION_TOO_LARGE`. |
51| Not supported | Postgres connection pooling (use direct connections), `postgres_fdw`, Heroku review-app `app.json` add-on provisioning. |
52
53### Salesforce Canvas: Signed Request vs OAuth Web Server Flow
54
55Canvas has two auth models — Salesforce (the embedding container) signals to the Heroku app (the embedded UI) which user is logged in.
56
57- **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.
58- **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.
59
60Recommend Signed Request for any embedded-only Canvas app; OAuth for hybrid (embedded + standalone) apps.
61
62---
63
64## Decision Guidance
65
66| Situation | Recommended Approach | Reason |
67|---|---|---|
68| Heroku app needs a local Postgres copy of Account / Contact / Custom Objects | **Heroku Connect** | Managed bidirectional sync; eventual consistency |
69| 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 |
70| Salesforce users want to search / report on Heroku transactional data without copying | **Heroku External Objects** | Salesforce Connect (oData) virtualizes the tables |
71| 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 |
72| Heroku app needs occasional Salesforce data — not a continuous mirror | **Heroku → Salesforce REST API** with JWT bearer flow | No add-on, just OAuth |
73| Salesforce trigger needs synchronous data from a Heroku microservice | **Apex callout via Named Credential** | Same governors as any callout — bulkify |
74| Embed a Heroku UI inside Salesforce for end users | **Canvas (Signed Request)** | Default auth; no consent prompt |
75| Demo / proof-of-concept: 1,000 records, daily check-ins | **Heroku Connect demo plan** | Free, 10K-row cap, 10-min polling — fine for POC |
76| Production: 1M+ rows, sub-minute lag | **Heroku Connect Enterprise / Shield** | Demo plan cannot meet production SLAs |
77| 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 |
78
79---
80
81## Common Patterns
82
83### Pattern A — Heroku app with local Postgres mirror
84
85**When to use.** A Heroku web app whose business logic is database-heavy
86(joins, aggregates, full-text search) and whose source of truth lives in
87Salesforce.
88
89**How it works.** Heroku Connect add-on provisions on top of Heroku Postgres.
90Configure object mappings in the Connect dashboard (Salesforce → Postgres
91read-only, or bidirectional). Use a dedicated Salesforce integration user
92with `API Enabled` + `View All` + `Modify All`. Region-align Heroku Postgres,
93Connect, and Salesforce.
94
95**Why not the alternative.** A custom polling job hitting Salesforce REST
96API has zero managed retry, no trigger-log replay, and no easy way to
97write back. Connect is the managed equivalent.
98
99### Pattern B — Heroku-hosted API exposed to Flow / Agentforce
100
101**When to use.** A Python / Node service does ML scoring, document parsing,
102or any computation Apex isn't suited for, and a Salesforce admin / agent
103needs to invoke it from a Flow or Agentforce action.
104
105**How it works.** Configure Heroku AppLink on the Heroku app. Salesforce
106admins discover the exposed actions in Setup → External Services / Flow
107Builder; agents discover them as registered tools. No Apex callout class
108needed; auth + parameter shape is handled by AppLink.
109
110**Why not the alternative.** Writing an Apex `@InvocableMethod` wrapper
111around an HTTP callout works but adds a code maintenance surface for
112something the platform handles natively now.
113
114### Pattern C — Virtualized Heroku Postgres data inside Salesforce
115
116**When to use.** Heroku is the system-of-truth for some transactional data
117(orders, sessions, telemetry) and Salesforce users need to view / search /
118report on it from a Lightning record page.
119
120**How it works.** Heroku External Objects exposes Postgres tables as oData
121endpoints; Salesforce Connect consumes them as External Objects. The data
122stays in Postgres; Salesforce queries it on demand.
123
124**Why not the alternative.** Heroku Connect copies the data into Salesforce
125storage (data + index costs). External Objects is read-mostly virtualization
126— no storage cost, but join + filter performance is bounded by oData round
127trips.
128
129---
130
131## Recommended Workflow
132
1331. **State the integration in one sentence.** Direction, latency, volume, where the source of truth lives.
1342. **Walk the Decision Guidance table.** First match wins. If two rows match, the more specific one (volume / latency) takes precedence.
1353. **Choose plan tier.** Demo = POC only; Enterprise / Shield = production. The 10K-row cap on demo is the most common surprise.
1364. **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.
1375. **Co-locate regions.** Heroku Postgres, Connect add-on, Salesforce instance. Mismatched regions are the #1 latency surprise.
1386. **For Canvas: Signed Request first.** OAuth Web Server Flow only if the app also lives outside Salesforce.
139
140---
141
142## Review Checklist
143
144- [ ] Decision: which of the six paths, with one sentence justifying it against the alternatives.
145- [ ] Plan tier explicit (demo vs Enterprise vs Shield).
146- [ ] Integration user is dedicated to the Heroku Connect add-on (not shared with other integrations).
147- [ ] Salesforce integration user has `View All` (large-query performance depends on it).
148- [ ] Heroku Postgres / Connect / Salesforce regions are co-located.
149- [ ] If Canvas: Signed Request unless explicit reason for OAuth.
150- [ ] If Connect: trigger-log retention matches recovery SLO (7d demo, 31d Enterprise).
151- [ ] No Postgres connection pooling on the Connect-attached database.
152
153---
154
155## Salesforce-Specific Gotchas
156
1571. **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](https://devcenter.heroku.com/articles/heroku-connect))
1582. **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.)
1593. **Re-authenticating Connect to a different org is not supported.** Sandbox refresh requires recreating the Connect connection from scratch. (See `references/gotchas.md` § 3.)
1604. **Postgres connection pooling breaks Connect.** Use direct connections from your Heroku app dyno. (See `references/gotchas.md` § 4.)
1615. **`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.)
1626. **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.)
163
164---
165
166## Output Artifacts
167
168| Artifact | Description |
169|---|---|
170| Decision recommendation | One paragraph naming the chosen path, plan tier, integration user model, and region. |
171| Connection runbook | Integration user provisioning, plan tier procurement, region pinning, OAuth refresh cadence. |
172| Risk register | Limits the design will get within 50 % of (row count, polling cadence, region latency) plus mitigation. |
173
174---
175
176## Related Skills
177
178- `integration/aws-salesforce-patterns` — sibling skill for the AWS path; same decision-matrix shape.
179- `integration/event-relay-configuration` — Pub/Sub → EventBridge for AWS; for Heroku-side Pub/Sub subscribers the same Pub/Sub API is the entry point.
180- `architect/hybrid-integration-architecture` — broader topology decisions; consult before picking a Heroku path if AWS, MuleSoft, or self-hosted are also options.
181- `standards/decision-trees/integration-pattern-selection.md` — the master integration decision tree; Heroku is one branch.
aibot88