Building an Onboarding Workflow in Braze, Step by Step

An onboarding workflow in Braze is a Canvas that starts when a new user does something, waits, checks what they did next, and stops messaging them once they reach the goal. Build it in a fixed order: decide the goal, set entry, set exit, build the steps, then test. This guide covers each decision and the mistakes worth planning for.

‍

Key Takeaways

• Pick one activation event first, then derive the conversion event, the exit rule and the conversion window from it.
• Action-based entry suits onboarding. Trigger on the behaviour and filter on something stable, because Braze documents a race condition when the trigger and the audience filter match.
• A user who performs the exit event is marked to exit at once, but a user inside a Delay step stays there until the delay ends.
• Set the conversion window after you know the longest path in the Canvas.
• Users advance through a Message step even when no message reached them, so separate those who received it before a nudge branch.
• Preview first, then run a live test with a duplicate Canvas restricted to test users, and decide the control group before launch.

‍

What should you decide before you open the Canvas builder?

Pick one activation event first. It is the action that shows a new user has understood the product, such as saving a first item or completing a profile. Choosing it late means rework in three places.

Braze documents where it shows up. Conversion events measure the efficiency of your Canvas. The Canvas QA checklist says to align exit events with your primary conversion, or add segment-based exits so users leave the journey when they convert or no longer qualify.

‍

How do you build an onboarding workflow in Braze, in what order?

Braze's Create a Canvas guide runs from basics to launch. For onboarding we recommend following the same stages, in this sequence, because each one depends on the one before.

1. Name the Canvas, tag it, and assign the conversion event you chose.
2. Choose the entry schedule.
3. Set the target audience and the entry controls.
4. Set the exit criteria.
5. Set send settings: subscription, rate limiting and quiet hours.
6. Build the journey: message, delay, then Action Paths.
7. Preview, run a live test with test users, then launch.

‍

You needn't start from a blank canvas. Braze notes you can save time by starting from a Canvas template. Its onboarding template expects three emails prepared in advance: a welcome email, an email with tips on how to use your app, and a feedback email that includes a user survey.

‍

Which entry schedule suits an onboarding workflow?

Action-based entry fits. With action-based delivery, users enter the Canvas and begin receiving messages when they take particular actions, such as opening your app, making a purchase, or triggering a custom event. The new user's first meaningful action starts the clock.

The classic trap is a trigger and an audience filter that describe the same behaviour. Braze warns that a race condition may mean the user is not in the audience when they perform the trigger event.

In onboarding that can mean triggering on a first session while filtering on a session attribute. We recommend triggering on the behaviour and filtering on something stable, such as when the user first used the app.

One more check belongs here. If an action-based Canvas sends messages earlier than expected, Braze says to check that the custom event timestamp carries the current time instead of a backdated time.

‍

Who should enter, and how often?

Braze's own example is a segment of users who first used your app less than a week ago. Its onboarding template targets users who first used an app less than one day ago. Pick your window from how quickly the product is meant to be understood.

Entry controls determine if users are allowed to re-enter a Canvas. For action-based entry, the volume cap can be hourly, daily, or the lifetime of the Canvas. Braze also advises setting the re-eligibility window correctly to prevent over-messaging or retargeting issues.

For a first-week journey we'd keep re-entry off unless you've designed a reinstall flow on purpose. A returning user who re-enters a welcome journey may read the welcome email as an error.

Before launch, select Calculate exact statistics in the target population summary. Braze notes the displayed population excludes users who aren't contactable through various message channels.

‍

How do exit criteria and conversion events work together?

When a user performs the exit event, Braze immediately marks them to exit the Canvas. If they're in a Delay step, they remain in that step until the delay period ends. A user who converts early in a long delay is marked to exit at once.

They still occupy the step until it finishes. The exit criteria page covers the detail.

Conversions and exits are counted differently. Conversions are tracked even after the Canvas ends, but exits are not tracked once the user exits the Canvas. The minimum time for a conversion window is five minutes, and the window extends to three days beyond the maximum duration of the Canvas.

We recommend setting the conversion window after you know the longest path. Braze advises setting it to at least match the longest path in the Canvas.

The maximum duration is the longest possible time a user can take to complete the Canvas, so draw the journey first and read that figure off it. A window chosen before the journey exists tends to be too short for the journey you build.

‍

How should the steps be sequenced?

A workable skeleton is a Message step, a Delay step, an Action Paths step, then a branch for each outcome. Braze recommends using the Delay step in the journey so users aren't overwhelmed by repeated messaging. The table shows what each step contributes and the documented behaviour to check, drawn from the Delay, Action Paths and Message pages.

‍

Action Paths deserves care. A user who performs a trigger event advances through the relevant action group based on the first qualifying action after entering the step.

If the trigger is starting a session and the next step is an in-app message, the user must perform two session starts to receive that message. Braze also says not to change the ranked-order setting after launch while users are in the step.

‍

How long should the delays be?

Braze documents how delays work but gives no recommended onboarding length, and we have no verified benchmark to offer. We suggest sizing each delay from how long the activation action realistically takes your users, then checking it against your own data after launch. A delay set from calendar habit is a likely reason for a nudge landing before the user has had time to act.

Three documented behaviours affect the choice. Changes to user attributes or contact information during the delay are reflected when the user advances. An email address added mid-delay is therefore usable at the next step.

If a selected date and time have already passed when users reach a Delay step, users exit the Canvas. A Delay component with no subsequent steps advances users out of the Canvas, so a trailing delay does nothing.

‍

Which send settings protect new users?

Braze says rate limiting or frequency capping helps ensure you aren't over-messaging users. Its release notes also list Message Prioritization as generally available, in an entry dated 15 Oct 2026.

It is an optional layer on top of frequency capping. Subscription settings apply on a per-step basis, so they have no effect on the entry audience.

Quiet hours behave in a specific way. When Send at next available time is selected, quiet hours suppress the message and send it at the next available time outside quiet hours. The QA checklist flags that Intelligent Timing and quiet hours conflict, so choose one.

The failure mode we watch for is unreachable users being read as unengaged. A Message step advances users when a message is frequency capped and not sent, and when a user is not reachable by channel. Those users reach your Action Paths step and fall into Everyone Else.

A nudge meant for people who ignored your welcome email then also goes to people who never received it. To advance only users who receive a particular message, Braze says to add a Decision Split step directly after your Message component.

‍

How do you test an onboarding workflow before launch?

Test in layers, cheapest first. Braze describes the preview as quality assurance that your messages are sent to the right audience, all before sending your Canvas. The table sets out the order we'd use.

‍

Read the caveats before you run a preview. Test users enter the preview even if they aren't eligible in real life.

Braze processes Liquid logic during a test run even when no test message is sent, and Connected Content executes during preview user paths. For the live test, Braze suggests reducing delays to about one second, and the test Canvas guide notes that test users may not receive a message for reasons that include frequency capping limitations.

In-app messages and Content Cards depend on an SDK session rather than a dashboard test send, so test them inside the app. For push, confirm that rich media loads, action buttons work, and you've tested both iOS and Android. Braze also says to test all components in your development environment before launching.

‍

What should you check first after launch?

If you see many entries but few sends, start with channel eligibility. Braze points to a channel-eligibility or subscription-state filter, an overly tight delivery control, or control-group size as the usual causes. Delivery validations, an additional check at message send to confirm your audience still meets your criteria, are one control to review.

We recommend deciding the control group before launch. Braze notes you can add one by adding a new variant, and its QA checklist says you can't add a control group retrospectively.

For onboarding, a held-back group is the only way to show the Canvas changed behaviour. Keep the build small too: a Canvas can hold up to 200 steps, but a first-week journey rarely needs a fraction of that.

‍

What does this look like for a hypothetical budgeting app?

Take a hypothetical budgeting app whose team defines activation as connecting a first account. The Canvas enters users on their first session.

The audience filter uses the date they first used the app, so trigger and filter describe different things. A welcome message goes out, then a delay sized from the team's own analytics on how long connecting takes.

After the delay, an Action Paths step waits for the account-connected event. Users who connect take the matching group and exit. Everyone Else gets a single nudge, but only after a Decision Split confirms the welcome message was received.

The exit event, the conversion event and the Action Paths trigger are all the same event. The conversion window is set once the longest path is known. No outcome is claimed here.

The example shows the decisions and their order.

‍

How does this connect to the rest of the onboarding programme?

An onboarding workflow is one part of a larger programme. To choose what to measure once it's live, see measuring onboarding success with key metrics in Braze. If first open happens on mobile, onboarding new mobile users from first open covers questions this guide leaves out.

Once the skeleton works, personalised onboarding experiences in Braze shows how to vary the journey by user. For the nudge, push notifications for onboarding completion is the natural companion. Feedback surveys in Braze covers the survey email the template expects, and onboarding and engagement in Braze covers the wider strategy.

As a Braze implementation partner, CustomerIK recommends writing the activation event, the exit rule and the conversion window on one page before anyone opens the builder, then reviewing that page after the first full cohort has gone through.

‍

Frequently Asked Questions
‍

1. Should an onboarding Canvas use action-based or scheduled entry?

Action-based entry fits best, because users enter when they take particular actions such as opening your app. Scheduled entry runs on a time schedule instead.

2. How long can a Delay step be?

Braze says you can extend Delay steps up to two years (730 days). Its own onboarding example is an extended delay before nudging users who haven't started a session.

3. What happens if a user converts while in a delay?

Braze marks them to exit immediately. They remain in the Delay step until the delay period ends and don't proceed into later steps.

4. How long can an Action Paths evaluation window be?

The default is one day. The maximum evaluation window for an Action Paths step is 31 days.

5. Do unreachable users still move through a Message step?

They do. Braze lists a user not being reachable by channel as one condition under which users advance. A Decision Split after the Message step can separate those who received it.

‍

Sources

• Braze, Create a Canvas. Retrieved 29 Oct 2026.
• Braze, Exit criteria. Retrieved 29 Oct 2026.
• Braze, Delay. Retrieved 29 Oct 2026.
• Braze, Action Paths. Retrieved 29 Oct 2026.
• Braze, Message. Retrieved 29 Oct 2026.
• Braze, Matching exit criteria to entry events. Retrieved 29 Oct 2026.
• Braze, Canvas QA checklist. Retrieved 29 Oct 2026.
• Braze, Send test Canvases. Retrieved 29 Oct 2026.
• Braze, Preview user paths in Canvas. Retrieved 29 Oct 2026.
• Braze, Onboarding Canvas template. Retrieved 29 Oct 2026.
• Braze, Release notes. Retrieved 29 Oct 2026.
• Braze documentation changes over time, so check the linked pages for current behaviour before you build.
• Written by CustomerIK, a Braze implementation partner.

‍

CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.

If you are planning an onboarding Canvas and want a second pair of eyes on the entry and exit rules, let's talk.

‍