Salesforce + Braze integration architecture
How to connect Salesforce and Braze today with APIs and middleware: systems of record, identity, consent, channels, measurement and error handling.
Many teams run Salesforce for CRM and Braze for customer engagement across app, web and messaging channels. Connecting them well means deciding which system owns each kind of data, moving changes reliably in both directions, and keeping consent consistent. This page gives a reference architecture for that integration as it can be built today.
This is a reference design. We validate the APIs, licences and permissions on both sides for each implementation, and GeekMidst can design and implement it through Salesforce and Braze integration.
Business context
Braze documents no native Salesforce connector, and its Technology Partners index does not list Salesforce. Braze documents one Salesforce recipe, "B2B Salesforce Sales Cloud", which uses Braze webhooks to create and update Lead records. Braze describes it as "a community-submitted integration and isn't directly supported by Braze", and it is one-way, from Braze to Salesforce. Braze's B2B data model guidance maps Salesforce Accounts and Opportunities to Braze Catalogs and Lead and Contact IDs to user aliases. Everything else is built with the two platforms' APIs and an integration layer. Third parties advertise connectors, but they are not Braze-documented. Read more in our Salesforce and Braze integration guide.
Salesforce + Braze reference architecture
Reference architecture: a reusable pattern, not a live client integration
Select a component to see what it is responsible for and how data moves to and from it.
Components and data flows (text version)
| Component | Type | Responsibility |
|---|---|---|
| Salesforce CRMSales and Service Cloud | Salesforce product | System of record for accounts, contacts, leads, opportunities and cases, and the source of the customer ID. |
| Marketing Cloudif used | Salesforce product | Keeps any programmes that stay on Marketing Cloud. Needs a clear rule on which platform messages whom. |
| Data 360if used | Data and analytics | Unified profiles, insights and segments. Reaches Braze only through the integration layer or a warehouse share. |
| Event and integration layermiddleware or iPaaS | Integration layer | Subscribes to Salesforce changes, maps them to Braze calls, and turns Braze engagement into CRM updates. |
| Identity, consent, governancemapping rules | Identity, policy and governance | Owns the customer ID mapping, consent precedence rules and which fields may leave each system. |
| Error queue and reconciliationreplay and audit | Integration layer | Holds failed messages with context for replay, and runs scheduled reconciliation between the two systems. |
| Monitoringalerts and dashboards | People | Watches throughput, errors, rate-limit responses and reconciliation results, with a named owner. |
| Braze workspaceprofiles, events, catalogs | Engagement platform | Braze user profiles keyed by external_id, with custom attributes, events, purchases and catalogs. |
| Canvas and campaignsjourneys and messages | Engagement platform | Braze campaign execution: Canvas journeys and single-message campaigns, scheduled, action-based or API-triggered. |
| Currentsengagement event stream | Data and analytics | Braze describes Currents as a real-time stream of engagement events. It sends them to storage, CDPs or a Custom HTTP Connector, depending on your package. No Salesforce destination is listed. |
| Channel or touchpoint | Email from Braze, governed by Braze subscription states. | |
| Push and in-appBraze SDKs | Channel or touchpoint | Push, in-app messages and Content Cards delivered through the Braze SDKs. |
| SMS and WhatsAppsubscription groups | Channel or touchpoint | Messaging channels that require Braze subscription groups. |
| Engagement data storewarehouse or storage | Data and analytics | Receives Currents data so engagement can be summarised before it reaches CRM. |
Data flows
- Salesforce CRM → Event and integration layer: record changes. Change Data Capture or Platform Events over the Pub/Sub API, batched where volume is high. Replay from the retention window after an outage.
- Data 360 → Event and integration layer: segments and insights. Data actions call a webhook in the integration layer, or data is shared to a warehouse for Braze Cloud Data Ingestion.
- Marketing Cloud → Identity, consent, governance: suppression and consent. Opt-outs recorded in Marketing Cloud are extracted by the integration layer, through APIs or file exports, and applied by the consent rules so Braze does not message the same person.
- Event and integration layer → Identity, consent, governance: mapping check. Each payload is checked against ID mapping and consent rules before it is sent.
- Event and integration layer → Braze workspace: /users/track. Attributes, events and purchases by external_id. Respect Braze rate limits; on 429, back off using the rate-limit headers.
- Identity, consent, governance → Braze workspace: subscription updates. Consent changes use the Braze email status or subscription group APIs, so the owner's decision is applied.
- Event and integration layer → Error queue and reconciliation: failed calls. Failures are queued with the source ID and payload for replay; nothing is dropped silently.
- Braze workspace → Canvas and campaigns: audiences and triggers. Segments and API-triggered entries start Canvases and campaigns.
- Canvas and campaigns → Email: email. Sent to users whose subscription state allows it.
- Canvas and campaigns → Push and in-app: push and in-app. Push targets subscribed or opted-in users with foreground push enabled; in-app messages and Content Cards are delivered through the SDKs.
- Canvas and campaigns → SMS and WhatsApp: SMS and WhatsApp. Sent only to users subscribed to the right subscription group.
- Currents → Engagement data store: engagement events. Currents streams events in Avro to storage. Gaps are detected by comparing counts.
- Engagement data store → Event and integration layer: engagement summary. Summarised engagement, not raw events, is written back to CRM through the integration layer.
- Event and integration layer → Salesforce CRM: CRM updates. Engagement summaries and lead updates are written through Salesforce APIs as an integration user.
- Error queue and reconciliation → Monitoring: alerts. Queue depth and reconciliation differences raise alerts to the owner.
Systems of record
| Data | Recommended owner | Why |
|---|---|---|
| Customer identity | Salesforce CRM customer ID, mapped to Braze external_id | CRM is where records are created and merged; Braze discourages email as external_id |
| Consent | One owner per channel, applied to the other system | Two owners lead to conflicting states; Braze push and SMS have their own subscription models |
| Audiences | Data 360 or CRM for business segments; Braze for engagement segments | Keep each segment defined in one place |
| Events | Braze for in-app and messaging events; CRM for business events | Send only summaries back to CRM |
| Campaign execution | Braze for its channels; Marketing Cloud only for programmes deliberately kept there | Avoid two platforms messaging one person |
Component responsibilities
| Component | Responsible for |
|---|---|
| Salesforce CRM | Customer records, sales and service context, customer ID |
| Integration layer | Subscriptions, mapping, retries, rate-limit handling, write-back |
| Identity and consent rules | ID mapping, consent precedence, field allow-list |
| Error queue | Replay, audit and reconciliation |
| Braze | Profiles, segmentation, Canvas, channel delivery |
| Currents and data store | Engagement export and summarisation |
Data flow, step by step
- A CRM record changes. Change Data Capture publishes it; the integration layer receives it over the Pub/Sub API.
- Rules are applied. The layer checks the ID mapping and consent rules and removes fields that should not leave Salesforce.
- Braze is updated. The layer calls
/users/trackwith the external_id. Requests need an API key with theusers.trackpermission; Braze documents a burst limit of 3,000 requests per three seconds for customers with data points in their pricing, otherwise by contract. - Braze engages. Canvases and campaigns send through Braze channels to users whose subscription state allows it.
- Engagement is exported. Currents streams engagement events to storage, where they are summarised.
- CRM is updated. The layer writes summaries back to CRM records.
- Reconciliation runs. A scheduled job compares IDs and consent states and raises differences.
Trust boundaries and authentication
There are three trust zones: your Salesforce org, your integration layer and the Braze workspace. Braze REST API keys are scoped per endpoint and can have IP allowlists, which cannot be edited after creation, so create one key per purpose. On the Salesforce side, use an External Client App and a least-privilege integration user; connected apps support ends in Summer '27. Braze is a data processor and you are the controller, so plan data transfer terms with your legal adviser.
Failure scenarios and how to handle them
| Failure | Effect | How to handle it |
|---|---|---|
| Braze returns 429 | Updates delayed | Back off using rate-limit headers; batch up to 75 objects per request |
| Salesforce subscriber falls behind | Missed changes | Replay within retention, then reconcile |
| Duplicate external_id or merge | Split or merged profiles | Merge in CRM first; use Braze /users/merge carefully |
| Consent differs between systems | Message to an opted-out person | One owner per channel; reconcile daily |
| Write-back floods CRM | Lock errors and noise | Summarise; write once per period |
Operational monitoring
Monitor events received and sent, Braze response codes, queue depth, write-back failures and reconciliation differences. Alert a named owner on consent mismatches first, because they carry the most risk.
Alternative approaches and trade-offs
Middleware (the pattern above) gives control and monitoring but needs building and running. Warehouse-first sharing to Braze Cloud Data Ingestion reduces custom code but adds sync delay. Third-party connectors may be faster to start; check their scope and support. The Braze webhook recipe suits only simple, one-way lead creation and updates, and Braze does not directly support it. Compare the platforms in Salesforce vs Braze.
Implementation checklist
- 01
Agree systems of record
Identity, consent, audiences, events and campaign execution
- 02
Design the ID mapping
CRM ID to external_id; aliases for leads
- 03
Design consent precedence
One owner per channel and how changes propagate
- 04
Choose the integration layer
Middleware or iPaaS with queues and replay
- 05
Create scoped credentials
One Braze key per purpose; Salesforce External Client App
- 06
Build and test in sandbox
Test volumes, 429 handling and replay
- 07
Set up reconciliation
Daily comparison of IDs and consent
- 08
Monitor
Throughput, errors and mismatches with owners
Related services and solutions
Salesforce and Braze integration
Our integration service
→Braze implementation
Workspace, data and Canvas setup
→Salesforce and Braze solution
Solution design and stages
→What the acquisition means
Our note on the pending deal
→Data 360 architecture
Activation paths, including Braze
→API-led integration
Layered integration design
→Questions we hear
Is there a native Salesforce to Braze connector?
Will the acquisition change this architecture?
Which system should own consent?
Is this from a client project?
Sources
- https://www.sec.gov/Archives/edgar/data/0001108524/000119312526425881/d516983dex991.htm
- https://www.sec.gov/Archives/edgar/data/0001676238/000095010326015917/dp255270_defa14a.htm
- https://www.braze.com/docs/user_guide/get_started/b2b_use_cases/b2b_salesforce_sales_cloud
- https://braze.com/docs/user_guide/get_started/b2b_use_cases/b2b_data_models/
- https://www.braze.com/docs/api/endpoints/user_data/post_user_track
- https://www.braze.com/docs/api/api_limits
Design your Salesforce and Braze integration
Tell us which systems you run and what should flow between them. We can define the systems of record and design the integration layer.
