Docs

Designing workflows

Throttle function

Learn more about the throttle workflow function within Knock's notification engine.

A throttle function allows you to limit the number of times a workflow is executed for a recipient within a given window. For example, in an alerting system, your recipients might only want to receive a single email per hour for a given alert. A throttle lets you express this logic within Knock.

Throttle functions are helpful when you want to control how often a workflow is executed for a recipient without needing to implement the logic within your own application layer.

How throttling works

Throttling works like a gate. When the throttle step is executed, the gate is checked; if the threshold over the window has been exceeded, then the workflow stops execution. If the threshold has not been met, then the workflow will proceed.

Throttle functions have 3 pieces of configuration:

A throttle window: the length of the throttle period.
A throttle threshold: the number of invocations allowed within the window. Defaults to 1 if none provided.
A throttle key (optional): An optional value to specify as the throttle key for the workflow run.

Setting a throttle window

The throttle window determines how long a throttle is active for the recipient. The window opens the first time the throttle function is executed in a workflow run for a recipient.

Set a fixed throttle window

You can set a fixed duration throttle window using the "Throttle for a fixed window" option in the throttle step. The window accepts a relative duration, which can be specified in seconds, minutes, hours, or days.

Set a dynamic throttle window

You can also set the length of your throttle windows dynamically using a variable. You can use any of the data, recipient, actor, or environment variables associated with the workflow run to set your dynamic throttle window.

When specifying a dynamic window you must provide one of the following:

An ISO-8601 timestamp (e.g. 2022-05-04T20:34:07Z) which must be a datetime in the future
A relative duration unit (e.g { "unit": "seconds", "value": 30 })
A window rule (e.g { "frequency": "daily", "hours": 9, "minutes": 30 })

A dynamic interval must be available to be resolved via the key you specify on the given schema, meaning that if you specify a key of throttleWindow in your data schema, your workflow trigger data must contain either an ISO-8601 timestamp, a valid duration unit, or a valid window rule.

When the key specified is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the throttle will be skipped.

A fixed timestamp will tell Knock to close the throttle window at the exact datetime you provide. It must be a valid ISO-8601 timestamp in the future.

An example timestamp

You can then reference that in your throttle step settings as data.throttleUntil.

A duration will take the current time that the step is executing and add the duration to it to produce the throttle window close time. A duration object is an entity that you can set on recipients, tenants, environment variables, or in your data payload and reference on your throttle step.

The duration schema

An example duration

Let's say you want to express a duration that throttles for 15 minutes, here's how you structure that:

You then reference that as data.throttleDuration in the throttle step configuration.

A window rule determines a dynamic interval for when the throttle should close. It allows you to express rules like "throttle until Monday at 9am."

The window rule will always be evaluated in the recipient's timezone (when set) and will fall back to the account default timezone, or "Etc/UTC".

The window rule schema

Example window rule

Let's say you want to express setting a window rule for throttling until Monday at 9am, here's how you might structure that on your recipient:

Now you can set the throttle window key to recipient.throttleWindow to reference this window rule.

Setting a throttle threshold

The throttle threshold determines how many invocations are allowed in the window before the threshold takes effect. By default, this value is set to 1, but you can change it as needed.

For example, if you want to say that you want to allow 5 invocations over a 1-minute window, then you would set the throttle threshold to 5.

Selecting a throttle key

A throttle function always runs per recipient. If you do not provide a throttle key, your throttle function will throttle for the executing step per recipient. If you do provide a throttle key, your throttle function will be evaluated for the key and executing step.

Custom throttle keys must be shorter than 64 characters long after being JSON and URL encoded.

Frequently asked questions

Yes! A dynamic throttle window can come from a variety of dynamic sources like the recipient, the environment, or within the data payload.

When a throttle is hit, the workflow will stop execution. You will be able to see this in your workflow run logs.

We haven’t added this ability, but if this is something you’re looking to do, please reach out to us to discuss your use case. We’d love to hear more.

A throttle is allowed to be opened for a maximum of 31 days. If you have a use case for a longer throttle window, please get in touch.

Absolutely, each throttle step is executed independently in a workflow, so you can have as many as you need.

Currently, you cannot throttle across Knock workflows. In the future, we will be exploring adding the ability to rate-limit the number of notifications a recipient can receive in a given window of time, which will work across workflows.

Currently, you cannot extend the throttle window past 31 days. If you need to throttle a workflow to run at most once per recipient, you can consider using workflow trigger frequency instead.