Controls are defined using JSON Schema or Zod, providing a strong run-time validation system for your workflows.

This ensures that you as the developer and your non-technical peers are speaking the same language. Those responsible for styling and copy can edit with confidence, knowing their changes are tested in code.

Controls vs Payload

Control Schema - For Non-Technical Peers and Developers. Managed in the Novu Dashboard UI, defined by developers and used by non-technical peers.

Payload Schema - For Developers. Passed during the novu.trigger method, and controlled by the developer.

Common usecases

  • Content - Modify any static content: email subject, email body, push notification title, etc…
  • Styling - Modify the styling of the content: button color, background color, font size, etc…
  • Behaviour - Modify the behaviour of the content: show/hide a section, show/hide a button, etc…
  • Order - Modify the order of the content: the order of the email sections, the order of the buttons, etc…
  • Actions - Modify the behaviour of actions: digest duration, etc…
  • Other - Any other use case that should be controller without modifying code

Step Controls

Step Control schema defines the control passed during the step method. These controls can be modified and persisted in the Novu Dashboard UI. The snippet below shows a configuration for the Step Control schema. If you don’t provide a schema, Typescript will infer the data type to unknown, reminding you of the best practice to specify your schema.

import { z } from 'zod';

workflow("new-signup", async ({ step, payload }) => {
    async (controls) => {
      return {
        subject: controls.subject,
        body: render(
      controlSchema: z.object({
        hideBanner: z.boolean().default(false),
        subject: z.string().default('This is the default subject'),
        components: z.array(z.object({
          type: z.enum(['header', 'cta-row', 'footer']),
          content: z.string()

Supported Schema Types

  • Zod Schema - A TypeScript-first schema declaration and validation library.
  • JSON Schema - The most popular schema language for defining JSON data structures.