Triggering workflows via the API

Learn more about how to trigger cross-channel notification workflows in Knock 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.

Trigger payload

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.

Passing data to your trigger

Pass schema data required by the workflow in your trigger call. The payload must be a valid JSON object.

The workflow builder determines which data keys are required.

Attributing the action to a user or object

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

Generating a cancellation key

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

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
`$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

Per-recipient trigger data

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.

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.

Frequently asked questions

You can trigger a workflow for a single recipient by passing a single recipient identifier to the recipients property in your trigger call.

You can trigger a workflow for multiple recipients by passing an array of recipient identifiers to the recipients property in your trigger call.

You can trigger a workflow for an object by passing an object identifier to the recipients property in your trigger call.

An object identifier looks like:

You can trigger a workflow for the subscribers of an object by passing an object identifier to the recipients property in your trigger call. Knock will automatically create a workflow run for each subscriber of the object.

It's not yet possible to trigger a workflow for an audience via the API. If you're looking to trigger a workflow for a specific audience, please get in touch with us. We're currently considering how to best support this use case and would love to discuss your specific needs.

You can trigger a workflow for up to 1000 recipients at a time. If you need to manage a larger 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.

It's not currently possible to issue bulk trigger requests to the API. If you need to trigger workflows for multiple recipients with per-recipient data, you can pass per-recipient trigger data.

You can cancel a workflow run by calling the cancel endpoint.

Yes, you can validate the data you're passing to a workflow trigger by providing a JSON schema in your workflow trigger step.