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.
Workflows are triggered via a call to the
notify endpoint, which tells Knock to run a specified payload of
data through the workflow specified by the call.
|key*||string||The human readable key of the workflow from the Knock dashboard|
|actor*||string||The user id of the user who performed the action|
|recipients*||string||A list of user ids for users that are associated with 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|
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.
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
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 notify run for the batch of recipients. A good example in an invite notification is the
idof 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
The cancellation key is scoped per workflow so you don't need to include the workflow key in the cancellation key.
You can optionally pass a
tenant to your
notify call that allows notifications generated during
the workflow execution to belong to that tenant.
You can read more about supporting multi-tenancy in our guide.