Canceling workflows

Learn more about canceling workflows in Knock and see code examples to get started.

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:

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

PropertyTypeDescription
key*stringThe human readable key of the workflow from the Knock dashboard
cancellation_keystringA unique identifier for the workflow run
recipientsRecipientIdentifier[]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:

  1. A cancellation cannot be performed on a specific channel step, it can only be performed against the entire workflow.

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

  3. Workflow cancellations are both deferred and executed concurrently to the workflow run itself. The cancel workflow API will return a 204 No Content response 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.

  4. Canceling a workflow with a batch step will not close the open batch window. Read more here.