Trigger Overrides

Trigger overrides let you to modify the default behavior of specific aspects of a workflow trigger (event), giving you fine-tuned control over how messages are delivered across different channels and providers.

Provider overrides

Provider overrides give you fine-tuned control over how messages are delivered by allowing direct configuration of the underlying provider SDKs during the workflow's trigger phase.

This feature is designed for advanced use cases where Novu's default message editor or UI does not expose specific provider capabilities.

Use provider overrides to:

• Access native provider features not surfaced by Novu’s abstraction layer. For example, custom headers in SendGrid, topic messaging in FCM, or Slack blocks.
• Adapt to provider-specific options by injecting parameters that Novu doesn’t yet officially support.
• Configure shared or unique settings across steps without altering templates or workflow logic.

This mechanism offers a flexible customization layer that lets you pass deeply nested payloads that align directly with your provider’s native API. It helps decouple workflow behavior from provider-specific implementation details, which is essential when working across multiple channels like email, push, or chat.

Override structure

Overrides are defined in the overrides property of a trigger payload. You can specify configuration values at two levels:

• Workflow-level: Applies to all steps using a specific provider and takes precedence over the default workflow provider settings.
• Step-level: Targets a specific step in the workflow and it takes precedence over both workflow-level overrides and the default workflow provider settings.

Workflow-level provider overrides

Workflow-level provider overrides apply configuration to all steps that use a given provider in the workflow. They’re useful for applying shared logic across multiple steps, without repeating the same settings in each one.

Use workflow-level overrides when:

• You need to define common metadata like headers, personalization, or layout settings.
• You want consistent behavior across all steps for a given provider.

import { Novu } from "@novu/api";
 
const novu = new Novu("<YOUR_SECRET_KEY_HERE>");
 
async function run() {
  const result = await novu.trigger({
    to: {
      subscriberId: "subscriber_unique_identifier",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
    },
    workflowId: "workflow_identifier",
    payload: {
      comment_id: "string",
      post: {
        text: "string",
      },
    },
    overrides: {
      providers: {
        sendgrid: {
          template_id: "xxxxxxxx", // Make sure this is a string
          trackingSettings: {
            clickTracking: {
              enable: true,
              enableText: false,
            },
          },
        },
      },
    },
  });
}
 
run();

This configuration affects every step in the workflow that uses SendGrid, unless a step-level override provides a more specific value.

Step-level provider overrides

Step-level overrides let you apply provider-specific settings directly to an individual step in your workflow.

Use step-level overrides when:

• You want to send push notifications through the same provider, but with different settings for each step. For example, two steps use FCM, but each sends a different sound or title.
• You need to customize the payload for a specific push step, such as platform-specific settings for Android and iOS, without affecting other steps.

import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });
 
async function run() {
  const result = await novu.trigger({
    to: {
      subscriberId: "subscriber_unique_identifier",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
    },
    workflowId: "workflow_identifier",
    payload: {
      comment_id: "string",
      post: {
        text: "string",
      },
    },
    overrides: {
      steps: {
        'push-step': {
          providers: {
            fcm: {
              notification: {
                title: 'New Comment',
                body: 'Someone replied to your post!',
                sound: 'default', // Play default system sound
              },
              android: {
                notification: {
                  sound: 'sound_bell' // matches res/raw/sound_bell.mp3
                }
              },
              apns: {
                payload: {
                  aps: {
                    sound: 'notification_bell.caf' // For iOS
                  }
                }
              }
            }
          }
        }
      }
    }
  });
}
 
run();

In this example, only the push-step is affected, and multiple FCM-specific settings are overridden for that step, which are the notification title, body, and sound configurations for both Android and iOS platforms.