KnockDocs

Triggering workflows

Workflows that you design within Knock are triggered from within your codebase by calling the notify endpoint and telling Knock who should be a potential recipient.

It's important to realize that calling notify in Knock may result in no messages being sent to your users. This is because calling notify will trigger a workflow, but your end users 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 notify 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

PropertyTypeDescription
key*stringThe human readable key of the workflow from the Knock dashboard
actor*RecipientIdentifierAn identifier of who or what performed this action
recipients*RecipientIdentifier[]A list of user ids, or object references of who to notify for this workflow
datamapA map of properties that are required in the templates in this workflow
cancellation_keystringA unique identifier to reference the workflow when canceling
tenantstringAn 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" }).

Response

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

Passing data

You can also pass the schema data required by the workflow into the notify 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.

Generating a cancellation key

Each notify 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 notify.

You can read more about canceling workflows in our guide.

Keep the following in mind when generating a cancellation key:

  1. Provide a value that allows you to uniquely identify the notify 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.

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

  3. The cancellation key is scoped per workflow so you don't need to include the workflow key in the cancellation key.

Multi-tenancy in notifications

You can optionally pass a tenant to your notify 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 notify 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 notify 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.