Salesforce and Braze Reference Build
An illustrative reference build, not a client project: welcome and reactivation journeys in Braze using Salesforce CRM data and app events, with a full test plan.
This is an illustrative blueprint. It is a reference architecture, not a write-up of a specific client project; outcomes depend on your data and setup.
This page describes a reference build that connects Salesforce CRM and Braze for two lifecycle journeys: welcoming new customers and reactivating inactive ones. It follows the Salesforce and Braze integration pattern and shows what a build would include, how it would be tested, and what we do not claim.
Status
Reference design. It has not been built as a client engagement, and no outcome is claimed. The APIs, editions and permissions it relies on are validated at the start of any real implementation.
Business problem, objectives and scope
A business sells through Salesforce and engages customers in an app. New customers get a generic welcome that ignores their account tier, and inactive customers receive promotions while they have an open complaint.
Objectives: a welcome journey that uses CRM context and app behaviour; a reactivation journey that respects open cases and consent; lifecycle stage visible to sales and service in Salesforce.
In scope: Contact data, account tier, open case count and email consent from Salesforce; sign-up, session and key-action events from the app; two Canvases; lifecycle writeback to the Contact. Out of scope: Data 360, Marketing Cloud, SMS and paid media.
Technology stack
- Salesforce CRM with Change Data Capture, read through the Pub/Sub API.
- An integration service, either middleware or a small custom service, holding secrets server-side.
- Braze with the SDKs in the app, Canvas, subscription states and Currents to a storage bucket.
Reference build: welcome and reactivation journeys
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 CRMsandbox first | Salesforce product | Holds contacts, account tier, open cases and the email consent field. Publishes contact changes as change events. |
| App and websiteBraze SDKs | Channel or touchpoint | Sends sign-up, session and key-action events, and identifies users with changeUser after login using the CRM contact ID. |
| Integration servicemiddleware or small service | Integration layer | Reads change events, maps fields, calls Braze, receives webhooks and writes lifecycle fields to CRM. Holds secrets and the dead-letter queue. |
| Braze test workspacewelcome and reactivation Canvases | Engagement platform | Runs an action-based welcome Canvas and a scheduled reactivation Canvas, with suppression for open cases and opt-outs. |
| Channelsemail, push, in-app | Channel or touchpoint | Seeded test users receive each message. Subscription state is checked before every send. |
| Currents to storagetest bucket | Data and analytics | Engagement and subscription events land in a storage bucket for test evidence and count checks; the integration service reads opt-out events from it. |
Data flows
- Salesforce CRM → Integration service: contact changes. Change Data Capture via the Pub/Sub API. The consumer stores its replay position; outages under 72 hours are replayed.
- App and website → Braze test workspace: SDK events. Sign-up, session and key-action events from the Braze SDKs.
- Integration service → Braze test workspace: attributes, consent. /users/track for attributes and /email/status for opt-outs. Back off on 429; dead-letter other errors.
- Braze test workspace → Channels: journey messages. Welcome steps after sign-up; reactivation after an inactivity window.
- Braze test workspace → Currents to storage: Currents events. Sends, engagement and subscription state changes in Avro.
- Braze test workspace → Integration service: stage webhook. A Canvas webhook reports lifecycle stage changes. Failed calls are logged in the integration service.
- Integration service → Salesforce CRM: lifecycle fields. Lifecycle stage and last engagement date written to the contact by an integration user. Rejected writes are queued for review.
Implementation approach
- Identity first. The CRM contact ID becomes the Braze
external_id, set withchangeUseronly after login, following Braze's advice not to identify users before they can be uniquely identified. - Consent owner. Salesforce owns email consent in this design; Braze unsubscribes flow back through Currents subscription events and the integration service.
- Data feeds. Change events are batched into
/users/track, up to 75 objects per request. - Journeys. An action-based welcome Canvas starts on the sign-up event, with Audience Paths by account tier. A scheduled reactivation Canvas targets users inactive for a defined window and exits anyone with an open case.
- Writeback. A Canvas webhook reports stage changes; the integration service writes them to the Contact.
Technical challenges, solution and trade-offs
Challenges and trade-offs
| Challenge | Design response | Trade-off |
|---|---|---|
| Anonymous app users before login | Track anonymously; identify after login | Pre-login events merge into the known profile when an existing ID is used |
| Opt-out made in Braze | Currents subscription events to the integration service | Adds a dependency on Currents, which depends on your package |
| Rate limits during backfill | Backfill through batched calls, off-peak | Backfill takes longer |
| Writeback to CRM | Integration service rather than direct webhooks to Salesforce | More to run, but retries and audit in one place |
| Profile merges | Reconcile in the warehouse | Merges are not reflected in Currents |
Deliverables
- Ownership matrix, field mapping and event schema documents.
- Integration service code and configuration, with a dead-letter queue and replay.
- Two Canvases with test users and a test log.
- Monitoring dashboard definitions and a runbook.
Test plan
| Test | What is checked | Pass condition |
|---|---|---|
| New contact | Change event creates or updates the Braze profile | Attributes match within the agreed time |
| Sign-up after login | Welcome Canvas entry and tier branch | Correct branch for each tier |
| Open case | Reactivation exit | No promotional message while a case is open |
| Opt-out in Braze | Currents event reaches CRM | CRM consent field updated |
| Opt-out in Salesforce | Consent reaches Braze | No further email sent |
| Braze 429 | Backoff and retry | No data loss |
| Consumer outage | Replay from stored position | All changes applied in order |
| Writeback failure | Dead-letter queue | Record parked and alerted |
Outcomes
No outcome is claimed. This is a reference design; any results would depend on your data, audience and content.
What is not claimed
- That this has been built for, or used by, any client.
- Any conversion, retention or revenue figures.
- That a native Salesforce to Braze connector exists, or that the announced acquisition changes this design.
Limitations
The design leaves out SMS, which needs subscription groups, and Data 360, covered on Data 360 and Braze. Freshness depends on change event processing and Braze rate limits in your contract.
Lessons from the documentation
Decide identity and consent ownership before any build, keep integration logic in one place you control, and test failure paths as carefully as the happy path.
Related
Integration services
Turn this design into a plan
→Integration guide
Step-by-step guide
→Braze implementation
Canvas and SDK build
→UAT test plan template
Plan your acceptance tests
→Sources
Scope a build like this
Tell us your lifecycle journeys and data. We can adapt this reference design to your org and Braze workspace.
