Triggering workflows via the API

The trigger API endpoint executes workflows for your recipients. When you call the trigger endpoint, Knock runs your specified Recipients and data through the workflow.

Learn more about triggering workflows in our API reference.

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

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.

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

Pass schema data required by the workflow in your trigger call. The payload must be a valid JSON object. There is a 1024 byte limit on the size of any single string value (with the exception of email attachments), and a 10MB limit on the size of the full data payload.

The workflow builder determines which data keys are required.

Pass an actor in your trigger call to attribute the workflow run to a specific user or object.

Calling a workflow trigger with an actor:

• Records who triggered the workflow
• Links the actor to any in-app feed messages
• Includes the actor in batch steps via the actors key
• Excludes the actor from notifications when they are a subscriber to an Object recipient

Include a cancellation_key in your trigger call to enable workflow cancellation.

You can read more about canceling workflows in our guide.

The key should uniquely identify the workflow run you want to cancel. We recommend using:

• A UUID v4
• A hash of relevant workflow data
• A timestamp combined with recipient and workflow identifiers

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
$trigger_data	Any recipient-specific trigger data to merge in with the data available on the workflow run
*	An arbitrary set of key/value pairs to set for the recipient

You can pass per-recipient data to your trigger by passing a dictionary of data under the $trigger_data property for each recipient. Any data provided under this property will be merged with the data passed in the data property to produce the final data available for the recipient's workflow run.

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.