Canceling workflows
Canceling a workflow allows you to stop a workflow run mid-execution. This action will stop the workflow from sending new messages to recipients. This can be useful in situations like reminder workflows, where a notification needs to be canceled once a user has performed an intended action.
Only workflows with a step that can pause the run can be canceled, since otherwise Knock will immediately send a notification to your recipients. The three steps that can pause a workflow run are:
- Batch functions will pause workflows while the batch window is open.
- Delay functions will pause workflows for the configured delay window.
- Fetch functions may pause workflows during a retry backoff.
Canceling a triggered workflow
To perform a cancellation, you first need to provide a cancellation_key in the workflow trigger request. Knock will use this key to uniquely identify the triggered workflow for cancellation.
You can read about generating workflow cancellation keys and some best practices in the triggering workflows guide.
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:
Gotchas and recommendations
There are a few fundamentals to consider when using workflow 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
archivea message instead. -
Workflow cancellations are both deferred and executed concurrently to the workflow run itself. The cancel workflow API will return a
204 No Contentresponse on success, but this only means Knock has successfully enqueued the cancellation request, not that the cancellation has been performed. We recommend against issuing a cancellation request within 5 seconds of a given workflow trigger. Cancellations issued too soon after a workflow trigger may not cancel the intended target. Cancellations issued prior to a workflow trigger may overtake and cancel the subsequent workflow. -
Canceling a workflow with a batch step will not close the open batch window. Read more here.