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.
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
actorskey - 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.