Canceling workflows
Canceling a workflow allows you to stop the sending of messages within a specified workflow for one or more recipients. This can be useful in settings like reminders where a notification needs to be canceled once a user has performed the intended action.
It's important to understand that only workflows that include a delay function or a batch function can be canceled within Knock, as without the built-in delay of a function Knock will immediately send a notification to your recipients.
Canceling a triggered workflow
To perform a cancellation, you first need to give Knock a pointer to understand how to uniquely
identify the triggered workflow by providing a cancellation_key
on the notify
call.
You can read about generating workflow cancellation keys and some best practices in the triggering workflows guide.
1const { Knock } = require("@knocklabs/node");
2const knock = new Knock(process.env.KNOCK_API_KEY);
3
4const userInvite = await invites.approve(inviteToken);
5
6await knock.workflows.cancel("new-user-invited", userInvite.id);
Schema
Property | Type | Description |
---|---|---|
key* | string | The human readable key of the workflow from the Knock dashboard |
cancellation_key | string | A unique identifier for the workflow run |
recipients | RecipientIdentifier[] | A list of specific recipient identifiers to cancel the workflow for (optional) |
Canceling for subsets of recipients
In some cases you may need to cancel a workflow for a subset of recipients only. You can do this by specifying the recipients list on the cancellation:
1const { Knock } = require("@knocklabs/node");
2const knock = new Knock(process.env.KNOCK_API_KEY);
3
4const userInvite = await invites.approve(inviteToken);
5
6await knock.workflows.cancel("new-user-invited", userInvite.id, {
7 recipients: ["user_1", "user_2"],
8});
Cancellation gotchas
There are a few things to watch out for when using cancellations:
A cancellation cannot be performed on a specific channel step, it can only be performed against the entire workflow.
You cannot cancel a given workflow run after it has finished ; if you need to revoke messages for persistent channels like the in-app feed, then you can
archive
a message instead.
You can learn more about using cancellation with batch and delay functions in our workflow functions guide.