Throttle Step

The Throttle step lets you limit the number of workflow executions within a specified time window. You can configure throttling directly in Novu workflow editor. By setting limits, you can prevent subscribers from receiving duplicate or excessive notifications when a trigger fires repeatedly.

Some use cases for this include:

• Limiting high-frequency alerts (such as CPU or billing usage checks) to one notification per hour, day, or week.
• Preventing duplicate messages from automated cron jobs or recurring triggers.
• Controlling notification frequency for subscribers who belong to multiple projects or contexts.

How the Throttle step works

At a high level, the throttle step counts the number of times a workflow is triggered for a specific subscriber.

• If the count is within the defined execution threshold for the time window, then the workflow proceeds as normal.
• If the count exceeds the threshold, then the workflow execution is halted at the throttle step. Any steps placed after the throttle step in your workflow will not be run. For example, if you have an email step following a throttle step, then that email will not be sent once the limit is reached.

Throttling applies consistently across channels, whether the workflow sends email, in-app, SMS, chat, or push notifications.

The throttle step applies to all workflows, including those marked as critical. If a critical workflow is triggered more frequently than the throttle limit allows, then it will be skipped just like any other workflow. This ensures that even high-priority alerts do not overwhelm a subscriber.

To the subscriber, the experience is transparent. They are not aware that any throttling has occurred; they either receive a notification or they don’t. The subscriber is never exposed to information about the throttle itself.

Throttle Step properties

You can find and edit all the properties for the Throttle step directly within the workflow editor.

• Navigate to the Workflow Editor: Go to the Workflows page in your Novu dashboard and either create a new workflow or select an existing one.
• Add the Throttle Step: On the workflow canvas, click the + icon between steps to open the step library, then select Throttle from the list.
• Access the properties panel: Click on the newly added Throttle step on the canvas. This will open its configuration panel on the right-hand side of the screen.

This panel contains all properties for the step, including:

• Name: A descriptive label for the step in the workflow editor.
• Identifier: A unique key used to reference the step programmatically.
• Throttle Window: The main configuration for setting the time period and execution limits.

Throttle window

The Throttle window defines the time period in which executions are counted. Within this window, only the specified number of executions are allowed.

In the Throttle step properties panel, you will find the options to set your Throttle Window. You can choose between two main modes:

• Fixed: Select this option to configure a predefined time window using the Throttle for and Execution threshold fields.
• Dynamic: Select this option to use a window defined in your trigger payload. You will then configure the Dynamic window key to specify which payload variable to use.

Fixed window

In fixed window, the time frame is predefined in the workflow editor. Use this mode when the time window for throttling is constant and known in advance. For example, "allow only one login alert per hour."

• Throttle for: Sets the fixed duration of the time window. The minimum duration is one minute. You can set this in minutes, hours, or days.
• Execution threshold: Defines the maximum number of workflow executions allowed within the specified time window. This defaults to 1.
• Group throttling by: By default, all throttling is grouped by the subscriberId. This field allows you to add a second aggregation key based on a variable from your trigger payload. This is useful for creating more throttling rules.

Here is an example of how they work together:

Imagine you want to send a notification for each project a user belongs to, but no more than once a week per project. You can set Throttle for to "7 days" and Group throttling by to payload.projectId. This ensures the user receives one alert for Project A and one for Project B within the same week, instead of just one alert total.

Dynamic window

In dynamic window, the time frame is determined by data sent in the trigger payload. Use this mode when the throttle duration or end time needs to be flexible and defined at the time of the trigger. For example, "throttle billing alerts until the end of the current billing cycle."

• Dynamic window key: Specify the key in your trigger payload that contains the dynamic window configuration. For example, payload.throttleUntil or payload.customWindow.

  The value for the dynamic window key can be provided in one of two formats:

  1. ISO-8601 Timestamp (string): This format throttles executions until a specific future date and time. Any new triggers before this timestamp will be evaluated against the throttle limit.

     {
       "throttleUntil": "2025-10-31T23:59:59Z"
     }

  2. Duration object: This format throttles executions for a duration relative to the time of the first trigger. It follows the same structure as the fixed window configuration.

     {
       "customWindow": { "amount": 30, "unit": "minutes" }
     }

• Execution threshold: Works the same as in the fixed window mode.

• Group throttling by: This also functions identically to the fixed window mode.