Variables

Variables within Knock let you set shared constants or secrets that you can use in all of the workflows and templates under your account. Variables can be overridden at the environment level to set per environment constants.

You can create account-wide variables on the Variables page under the Account section of your account settings. Each variable has a key and a value. The key is how you'll reference the variable in your templates, conditions, and preference conditions when building your workflows.

By default, any variables you set are created as public. Public variables are exposed via the user feed endpoint and are always visible within the dashboard by all team members. If you're working with variables that should not be exposed you can create them as secret variables by toggling the "Make variable secret" slider when creating a variable.

Secret variables are never revealed in the dashboard (all values are obfuscated) and are never exposed via the API.

Variables are available to be accessed under the vars namespace within your templates, step conditions, and preference conditions. For instance, if you set a variable with the key base_url you can access that variable under vars.base_url.

You can optionally set environment-specific values for your variables. To do so, go to the Variables page under the Account section of your account settings, click the three dots for a specific variable to select "Edit variable," and set the value for the environment you wish to override.

Knock stores every variable value as text, but at send time we try to parse that text as JSON first. If the value is valid JSON, your variable takes on the resulting type. If it isn't, we fall back to using the value as a string.

This means a variable is not always a string. A value of true becomes a boolean, and a value of 123 becomes a number.

Stored value	Parsed as
true / false	Boolean
123	Number
12.5	Number
null	null
["a", "b"]	Array
{ "unit": "seconds", "value": 30 }	Object
https://example.com	String
007	String (leading zeros aren't valid numbers in JSON)
TRUE	String (JSON is case-sensitive)

Because parsing happens before your templates and conditions are evaluated, compare a variable against the type it parses into. A variable set to true is a boolean, so compare it as one:

Comparing that same variable against the string "true" will never match.

Object and array values parse the same way, which makes variables useful for setting structured data under a single key. A support variable set to { "email": "help@example.com", "url": "https://example.com/help" } gives your templates both vars.support.email and vars.support.url, and lets you override the pair for each environment in one place.

Some features in Knock can consume a JSON object directly. For example, if you want to set a dynamic batch window, you can set a per-environment variable to contain { "unit": "seconds", "value": 30 } and reference that variable from your batch step.