Salesforce and Braze Integration
A reference pattern for connecting Salesforce CRM and Braze: data ownership, identity, consent, the integration controls to agree, and when not to build it.
Salesforce and Braze do different jobs. Salesforce CRM holds the commercial relationship: accounts, contacts, leads, opportunities and cases. Braze, which describes itself as a customer engagement platform, holds user profiles, app and web events, and the journeys that message people across channels. The real work is deciding which system owns each kind of data and each decision. This page sets out a reference pattern, its controls, and when a simpler design is better.
The business problem
Sales cannot see app engagement, Braze messages someone with an open complaint, an unsubscribe in one system is ignored by the other, and the same person exists twice. These come from unclear ownership, not from a missing API.
Five kinds of data, and where each usually lives
| Data | What it is | Usual owner | Typical flow |
|---|---|---|---|
| CRM data | Accounts, contacts, leads, opportunities, cases, owners | Salesforce CRM | Selected fields go to Braze as attributes, user aliases or catalog items |
| Marketing engagement data | Sends, opens, clicks, unsubscribes, conversions | Braze, for Braze-sent messages | Detail to cloud storage via Currents, or to Snowflake via Snowflake Data Sharing; summaries to CRM |
| Event streams | Sessions, sign-ups, purchases and other app or web behaviour | Your apps, through the Braze SDKs | Straight to Braze; to CRM only when a sales or service process needs it |
| Customer profiles | The person-level view used to target and personalise | Braze profile for engagement; CRM contact for the relationship; Data 360 if licensed | Kept in step through agreed identifiers |
| Activation destinations | Where a decision becomes a message or a task | Braze channels; CRM tasks or lead updates | Defined per use case |
Proposed architecture
The diagram is a reference design; we validate the APIs, edition and permissions for each implementation. The Salesforce and Braze reference architecture covers trust boundaries and failure scenarios in more depth.
Salesforce and Braze: reference integration pattern
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 |
|---|---|---|
| Data 360if licensed | Data and analytics | Optional unified profile and segmentation layer. No native Braze connector is documented, so its output leaves through activations, data actions or data sharing. |
| Salesforce CRMSales Cloud and Service Cloud | Salesforce product | System of record for accounts, contacts, leads, opportunities, cases and owners. Publishes record changes through Change Data Capture or Platform Events. |
| Apps and websitesBraze SDKs | Channel or touchpoint | Product surfaces that send sessions, custom events and purchases to Braze through the Braze SDKs, identifying users with changeUser. |
| Data warehouseoptional | Data and analytics | Optional staging point for bulk and modelled data. Braze Cloud Data Ingestion reads from Snowflake, Redshift, Databricks, BigQuery or Microsoft Fabric. |
| Integration layermiddleware, iPaaS or custom service | Integration layer | Maps fields and identifiers, batches calls, applies retries and throttling, and keeps API credentials server-side. Owns the dead-letter queue and replay. |
| Braze workspaceprofiles, Canvas, Campaigns | Engagement platform | Holds engagement profiles, segments, subscription states and journeys, and decides who receives which message and when. |
| Channelsemail, push, SMS, in-app and more | Channel or touchpoint | Messages sent by Braze on the channels configured for the workspace. Subscription groups control which users each sending resource can reach. |
| Currents destinationcloud storage or analytics tool | Data and analytics | Receives the Braze engagement event stream in Avro, for example in Amazon S3, Google Cloud Storage or Azure Blob Storage. Salesforce is not a listed Currents destination. |
Data flows
- Salesforce CRM → Integration layer: record changes. Change events through the Pub/Sub API. High-volume change events are kept for 72 hours, so a consumer that falls behind can replay from its last position.
- Data 360 → Integration layer: data actions. Data actions sent to a webhook that the integration layer receives. This is not a native Braze connection.
- Data 360 → Data warehouse: zero copy sharing. Insights shared out to a supported warehouse. Confirm the warehouse and feature availability for your org.
- Apps and websites → Braze workspace: SDK data. Sessions, custom events and purchases from the Braze SDKs. Users are identified only once they can be uniquely identified.
- Data warehouse → Braze workspace: CDI syncs. Scheduled Cloud Data Ingestion syncs, as often as every 5 minutes (the dashboard default minimum is 15). Alert on failed runs.
- Integration layer → Braze workspace: /users/track. Attributes, events and purchases, up to 75 objects per request. On a 429, wait for the retry header and resend; 401 and 403 go to the dead-letter queue.
- Braze workspace → Channels: messages. Canvas and Campaign sends, filtered by subscription state and subscription groups.
- Braze workspace → Currents destination: Currents events. Engagement events streamed in Avro. Profile merges are not reflected in Currents, so reconcile merged profiles downstream.
- Braze workspace → Integration layer: webhooks, Currents HTTP. Canvas webhooks and the Currents Custom HTTP Connector send lifecycle and engagement changes to the integration layer.
- Integration layer → Salesforce CRM: engagement summary. Aggregated fields or Lead updates written through the Salesforce API by a dedicated integration user. Failures are queued and retried.
Which platform owns which responsibility
| Responsibility | Salesforce | Braze | Integration layer |
|---|---|---|---|
| Account, opportunity and case records | Owns | Reads selected fields | Moves changes |
| Person identity | Owns contact and lead IDs | Stores them as external_id or user aliases | Maps and validates |
| App and web behaviour | Receives summaries if needed | Owns, through SDKs and /users/track | Optional forwarding |
| Journeys and messaging | Sales and service processes | Canvas and Campaigns | Triggers API-triggered entry where needed |
| Consent | One agreed owner per channel | Subscription states and groups | Syncs changes both ways |
| Engagement history | Summary fields only | Full detail, exported by Currents | Aggregates before writing to CRM |
Data flows and integration patterns
- CRM to Braze. Change Data Capture or Platform Events, read through the Pub/Sub API, feed the integration layer, which batches updates into
/users/track. Braze's B2B data model guide maps Accounts and Opportunities to Catalogs and Lead or Contact IDs to user aliases. - Warehouse to Braze. Cloud Data Ingestion (CDI) syncs attributes, events, purchases, subscription statuses and user deletes. See Braze data activation.
- Braze to Salesforce. Braze documents Canvas webhooks that create and update Leads, calling it "a community-submitted integration" that "isn't directly supported by Braze"; it is one-way and Lead-only. Currents lists no Salesforce destination.
- Third-party connectors. Massive Rocket, a third-party firm, lists a "Braze to Salesforce Connector" on the Braze marketplace with no technical detail, and Workato, Tray.ai and RudderStack also advertise connectors. None is part of Braze's own documentation. For Data 360, see Data 360 and Braze.
Integration controls to agree before the build
| Control | What to decide |
|---|---|
| Field mapping | Which CRM fields go to Braze, with types and owners; Braze strings hold up to 255 characters |
| Event schemas | Names, required properties and versions, agreed before development |
| Identity resolution rules | Which ID becomes the external_id; Braze discourages email, and identified users cannot revert to anonymous |
| Consent ownership | One system of record per channel and subscription group |
| API authentication | Braze REST keys are scoped per endpoint and cannot be edited later; a least-privilege Salesforce integration user |
| Rate limits | /users/track: 75 objects per request; 3,000 requests per three seconds burst for data-point pricing, otherwise by contract. /subscription/status/set: 5,000 per minute. Check your Salesforce API limits |
| Retries | Back off on 429 using X-RateLimit-Retry-After; never retry 401 or 403 |
| Duplicate prevention | One primary identifier per object; deliberate _update_existing_only; idempotent CRM writes |
| Ordering and freshness | Change event positions and timestamps; a freshness target per field |
| Retention | What each system keeps; Braze user deletion and CDI user deletes for erasure |
| Unsubscribe sync | Opt-outs both ways, by channel and group |
| Failure recovery | Dead-letter queue, replay within the 72-hour change event window, reconciliation |
| Testing and rollout | Sandbox and test workspace first, then a small audience |
| Operational ownership | A named owner, runbook and alerts |
Security boundaries and failure handling
Keep secrets in the integration layer, never in Canvas or app code. Braze keys can carry IP allowlists; Salesforce writeback uses OAuth with only the scopes needed (see named and external credentials). Park rejected Salesforce writes for review rather than dropping them, and reconcile counts and unsubscribes nightly. See the integration error handling checklist.
When a simpler architecture is better
- If Braze only needs a daily audience, a CDI sync from your warehouse may be enough, with no middleware.
- If sales only needs an MQL flag, the documented Lead webhook pattern may do.
- If you send only email and SMS from Marketing Cloud Engagement and have no app, a second platform may add cost without benefit; see Salesforce Marketing Cloud vs Braze.
Implementation stages
- 01
Discover
Use cases, data, owners and consent rules per channel.
- 02
Design
Ownership matrix, mapping, identifiers and the controls above.
- 03
Build
Integration layer, change events and Braze ingestion, outside production.
- 04
Test
Identity, consent, failure and volume tests with synthetic data.
- 05
Roll out
One journey and a small audience, then widen.
- 06
Operate
Monitor sync lag, errors and unsubscribe parity.
Available today vs proposed
| Item | Status |
|---|---|
| Braze REST API, SDKs, CDI and Currents | Documented by Braze |
| Braze webhooks to Salesforce Leads | Community-submitted pattern, not directly supported by Braze |
| Salesforce Change Data Capture and Pub/Sub API | Documented by Salesforce |
| Native Braze connector in Salesforce, or a MuleSoft Braze connector | Not found in vendor sources |
| This reference design | Proposed; validated per implementation |
Related
Salesforce and Braze integration services
How we scope and run the integration
→Integration guide
Step-by-step guide with mapping and schema examples
→Identity and consent architecture
Ownership of identifiers and opt-outs
→Reference build
An illustrative welcome and reactivation build
→Questions we hear
Is there a native Salesforce connector for Braze?
Not in the vendor sources we checked; Braze documents a community-submitted Lead webhook pattern.
Can Braze Currents send events to Salesforce?
Salesforce is not a listed Currents destination; route events through storage or the Custom HTTP Connector.
Does the acquisition change how we should integrate today?
Not yet. The deal is pending, so design on today's documented APIs.
Which system should own consent?
One per channel, agreed in writing. Everything else follows that owner and syncs changes quickly.
Sources
Plan your Salesforce and Braze integration
Tell us which use cases matter and where your data lives. We can map ownership, identity and consent with you before anything is built.
