Triggering workflows

Learn more about how to trigger cross-channel notification workflows in Knock.

Workflows that you design within Knock are triggered from within your codebase by calling the workflow trigger endpoint.

🌠

Knock terminology clarification. Throughout our documentation, you'll see us refer to notify calls and workflow triggers. These terms are synonymous.

It's important to realize that triggering a workflow in Knock may result in no messages being sent to your recipients. This is because your recipients may have indicated through their preferences that they don't wish to be notified by workflows of that type. The good news is that Knock handles all preference-based opt-outs for you automatically.

Triggering workflows

Workflows are triggered via a call to the trigger endpoint, which tells Knock to run a specified payload of Recipients and data through the workflow specified by the call.

Learn more about triggering workflows in our API reference.

Schema

Property	Type	Description
key*	string	The human-readable key of the workflow from the Knock dashboard
actor	RecipientIdentifier	An identifier of who or what performed this action (optional)
recipients*	RecipientIdentifier[]	One or more recipient references of who/what to notify for this workflow
data	map	A map of properties that are required in the templates in this workflow
cancellation_key	string	A unique identifier to reference the workflow when canceling
tenant	string	An optional identifier of the owning tenant object for the notifications generated during this workflow run

Recipient identifiers

When you want to identify a recipient in a workflow, either as an actor or as a recipient you can send either:

A string indicating a user that you have previously identified to Knock (e.g. user-1).
A reference of an object that you have previously set within Knock (e.g. { id: "project-1", collection: "projects" }).
A complete Recipient, to be identified inline during the workflow execution.

Response

Triggering a workflow will always return a unique UUID v4 representing the workflow run.

💡

Note: a workflow run ID is a unique identifier that represents the workflow run for all recipients of the workflow. Each individual in the workflow run will have a unique workflow recipient run ID, which is derived from the workflow run id.

Triggering a workflow for multiple recipients

You can always pass an array of multiple recipients to Knock, which will cause Knock to execute a workflow run for each recipient that you've passed in.

🚨

No more than 1000 recipients can be passed to each workflow trigger. If you need to manage a large list of recipients you might want to consider using our subscriptions feature to have Knock manage the set of recipients who need to be notified instead.

Attributing the action to a user or object

Knock supports passing an actor in your workflow trigger calls, which allows you to attribute the workflow trigger to an individual recipient (user or object).

Calling a workflow trigger with an actor will have the following effect:

The actor property will be available within your message templates including the full user or object that performed this action.
When the actor is also a subscriber to an Object recipient, they are always excluded from the recipients list. No notification will be sent to the subscribed actor.
When a workflow includes a batch step, the actor will be recorded as one actor who performed an action in the batch, which you can access via the actors key in your template.
Any workflows that contain an in-app feed channel step will produce a message that links the actor, and the actor will be loaded in any requests to this feed.

Passing data

You can also pass the schema data required by the workflow into the trigger call. The payload must be a valid JSON object, with nested objects and arrays supported.

The data requirements for the payload are determined in the workflow builder, including indicating which keys are required.

💡

For more information on validating trigger data and working with JSON schemas, see our guide on validating trigger data.

Generating a cancellation key

Each trigger call can optionally include a cancellation_key that allows you to uniquely identify it when canceling. Providing your own cancellation key means that you don't need to keep track of the Knock internal identifiers generated when calling trigger.

You can read more about canceling workflows in our guide.

Keep the following in mind when generating a cancellation key:

Provide a value that allows you to uniquely identify the trigger run for the batch of recipients. A good example in an invite notification is the id of a user invite so that we can easily stop reminders for that invite once a user has accepted it.
The cancellation key represents the workflow run, not the notifications generated per recipient, so you usually don't need to include a recipient identifier within the cancellation_key.
The cancellation key is scoped per workflow so you don't need to include the workflow key in the cancellation key.

Identifying recipients inline

You can pass a complete Recipient entity to the recipients or actor property when triggering a workflow. When passing the recipient, the recipients will be guaranteed to be identified before the workflow is triggered for the recipient with the properties passed in.

Property	Description
`id`	Required. An identifier for this user or object
`collection`	Required when identifying an object. Indicates the collection the object belongs to
`channel_data`	A dictionary containing a `channelId` key and a dictionary of channel data to be set for the recipient
`preferences`	A dictionary containing a preference set ID key and a `PreferenceSet` object to set for the recipient
*	An arbitrary set of key/value pairs to set for the recipient

Multi-tenancy in notifications

You can optionally pass a tenant to your trigger call. If you are a product that allows users to belong to multiple tenants, you'll want to pass a tenant to Knock in your trigger calls so that you can make sure a given user's in-app feed is scoped to the tenants to which they belong in your product.

You can read more about supporting multi-tenancy in our guide.

Triggering workflows with objects

For cases when you want to trigger an object in your system (either because it has its own in-app feed or because it's connected to a Slack channel), you'll include those objects in the recipients key of your workflow trigger.

An object reference always comes in the form of a dictionary with id and collection properties.

Remember, an object can also be an actor of a workflow as well!

Triggering workflows to subscribers of an object

You may also wish to fan out a workflow trigger to all subscribers of an object. You can do so by passing the object that has subscribers associated as a recipient:

Triggering workflows on a recurring schedule

Schedules allow you to express complex repeating schedules for your workflow triggers, so that you can trigger workflows on a one-off or a recurring basis for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

Learn more about schedules

Triggering workflows via source events

When you connect source to Knock from a customer data platform like Segment, you'll be able to use the events Knock receives to trigger workflows. You can create and manage event triggers for your workflows in the "Sources" section (under "Developers" in the sidebar) or directly from the workflow builder when you click the "Trigger" step.

From the Trigger step sidebar, if you have events connected to Knock you'll see the option to switch the trigger type to "Event" from the dropdown menu. Once here, you can select an event that when received will trigger this workflow. You can also map the critical fields needed to run a workflow to the fields that will be in the incoming event payload.

Learn more about sources

Conditionally executing a workflow trigger

A trigger step on a workflow can have one or more step conditions, which determine if the workflow will execute. When the conditions are evaluated as false, then the workflow will terminate and no other steps will be executed.

Controlling workflow trigger frequency

In some situations, you may want to limit the number of times that a recipient can run through a workflow. For example, for an account signup workflow, you may want to ensure that a recipient can only ever run through the workflow once. That's where workflow trigger frequency comes in.

Workflow trigger frequency lets you control the number of times that a recipient can run through a workflow, controlling if the workflow should trigger every time, or at most once for the recipient. By default, a workflow will trigger every time for a recipient.

If you specify a workflow trigger frequency of "Once per recipient", then you can also optionally choose to include the tenant in the frequency control. When set, your workflow will only trigger once per-recipient, per-tenant.

Frequently asked questions

←Merging users

Canceling workflows→