docs/platform/concepts/workflows.mdx
A Novu workflow defines the end-to-end process for delivering a notification to one or more subscribers across email, SMS, in-app, push, and chat channels. Workflows control what to send, when to send it, and which channels to use.
You can think of a workflow as a CI/CD pipeline for notifications or an assembly line:
Workflows can be simple:
Or complex:
It can also be extended further than these depending on your use case.
A workflow in Novu is built as a sequence of steps, each representing a distinct action or delivery mechanism. These steps are the building blocks of your notification logic. They determine what happens, when it happens, and how the message is sent to the user.
You define and arrange steps using the Workflow Editor in the Novu dashboard, where each node on the canvas represents a single step in the execution flow.
Each step operates independently, meaning that if one step fails, others can still succeed. This makes workflows both modular and fault-tolerant.
Each workflow can contain two types of steps: channel steps and action steps.
Channel steps deliver the actual notification through one of Novu’s supported channels. Each step contains its own notification template, content editor, and channel-specific settings.
Supported channel types include:
These steps allow you to introduce logic and flow control into the workflow. They don’t send notifications, but instead alter the timing or shape of the delivery pipeline.
Common action steps include:
Because steps are chainable, you can build complex notification sequences such as:
This allows Novu workflows to adapt to user behavior and preferences while keeping the configuration visual and testable.
All workflows in Novu are defined within the Workflow Editor, accessible via the Novu dashboard. This visual builder let's you define the sequence of steps such as sending emails, SMS, or in-app notifications that happen when a notification event is triggered.
Workflows created in the dashboard run via Novu’s Shared Bridge Endpoint, a centralized infrastructure that securely handles workflow execution for all customers. This means that your app doesn’t need to manage orchestration logic; Novu takes care of triggering, step execution, retries, and delivery flow behind the scenes.
<Note> While most users rely on the Shared Bridge Endpoint, Novu allows advanced users to host their own Bridge application and define workflows in code using the [Novu Framework](/framework). </Note>To learn more about building workflows using the workflow editor, filters, and personalizing templates, refer to the Building Workflows documentation.
Each workflow has a unique identifier used to reference it during API calls. While the workflow name can be changed, the workflow identifier becomes immutable after creating the workflow.
Workflow identifiers must be unique within one environment and are typically lowercase with hyphens (for example, order-confirmation).
Workflows can exist in one of three states:
| Status | What it means |
|---|---|
active | The workflow is ready to be triggered. Steps are valid, templates are complete, and all required integrations are connected. |
inactive | The workflow is paused. It cannot be triggered, but you can still edit its structure or steps. |
action required | The workflow contains one or more errors, such as missing required fields or unconnected channels. It can still be triggered. |
Tags are labels that help you organize and group workflows. They don’t affect delivery, but they play a major role in how notifications are filtered, displayed, or managed by both your app and your users via the Inbox component.
Use tags to:
security, account-activity, and marketing.Think of tags as your notification system's folders; they help your team stay organized.
security tagged notifications in a high-priority tab.marketing tagged workflows via preferences.Critical workflows are notifications that must always be delivered to users, regardless of their personal preferences. These workflows are essential to the user experience and system integrity, and users cannot disable them through notification settings.
Marking a workflow as critical ensures that high-priority messages are delivered without exception. This is particularly important for notifications that carry security, financial, or access-related information, where missing a message could have some consequences.
Examples of critical workflows include:
In Novu, syncing a workflow means copying it from one environment (typically development or staging) to another (such as production). This is how you deploy workflow changes without having to rebuild them manually across environments.
Instead of editing workflows directly in production, it's best practice to design and test them in a non-production environment first. Once validated, you can sync the workflow to production with a single action.
Every workflow in Novu is initiated by a trigger, which can be an external event or action that starts the notification flow. Triggers connect real-world events, such as a comment being posted or an order being placed, to a specific workflow using a unique identifier, the workflowId.
When you trigger a workflow, you send event data, including subscriber information, payload details, and optional overrides, to Novu’s API. Novu then validates the event, processes it, and orchestrates notification delivery across your defined channels.
Behind the scenes, Novu manages the full lifecycle: subscriber validation, workflow matching, attachment uploads (if applicable), queuing, job execution, retries, and status tracking.
To learn more about triggering workflows via API, handling payloads, and understanding the request lifecycle, refer to Triggering Workflows.
After a workflow is triggered, Novu tracks the full execution process in the Activity Feed. The feed gives you real-time visibility into each step, helping you debug issues, trace delivery problems, and understand how notifications behave in production. Each environment has its separate feed.
You can filter the Activity Feed by workflow name, channel type, time period, or transaction ID to easily find and inspect specific workflow executions.
When setting up a workflow, you can define channel preferences that determine how notifications are delivered to subscribers. In the Novu dashboard, you can set default preferences for each workflow, specifying which channels, such as email, in-app, SMS, or push, should be used by default during notification delivery.
These defaults ensure that subscribers receive messages through the most appropriate channels, even if they haven’t customized their own preferences. To learn more about channel preferences, refer to preferences.
Step conditions in Novu are used to control whether a step in your workflow should be executed, based on dynamic logic. This lets you create more intelligent and personalized workflows that respond to dynamic user and application data.
Conditions can be based on subscriber fields, payload data, or the results of previous steps. For example, you might skip sending an SMS if the user is already online, or send a follow-up email only if an in-app message hasn’t been read within 24 hours.
To learn more about all supported condition types, operators, and usage example, refer to the Step Conditions documentation.
These are some of the most frequently asked questions about workflows in Novu.
<AccordionGroup> <Accordion title="Do I have to create a workflow to send notifications?"> Yes, creating a workflow is mandatory to send notifications. </Accordion> <Accordion title="Can workflows be created and managed via code?"> Yes, workflows can be managed via code, if you are using Node.js, you can use the [Novu Framework](/framework/introduction) </Accordion> <Accordion title="Can all workflows be synced at once to another environment?"> Currently, only a single workflow can be synced at a time. </Accordion> </AccordionGroup>