Workflows

Trigger workflow

Changed on Sep 15, 2026

Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

post/v1/workflows/{key}/trigger

Request

Base URL: https://api.knock.app
URL: https://api.knock.app/v1/workflows/{key}/trigger
Auth: HTTP bearer

Path parameters

keystring required

Key of the workflow to trigger.

Request body

cancellation_keystring nullable

A key that is used to reference a specific workflow trigger request when issuing a workflow cancellation request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.

dataobject nullable

An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full data payload. Any individual string value greater than 1024 bytes in length will be truncated in your logs.

Example request

{
  "actor": "mr_dna",
  "cancellation_key": "isla_nublar_incident_1993",
  "data": {
    "affected_areas": [
      "visitor_center",
      "raptor_pen",
      "trex_paddock"
    ],
    "attraction_id": "paddock_rex_01",
    "evacuation_protocol": "active",
    "message": "Life finds a way",
    "severity": "critical",
    "system_status": "fences_failing"
  },
  "recipients": [
    "dr_grant",
    "dr_sattler",
    "dr_malcolm"
  ],
  "settings": {
    "sandbox_mode": true,
    "skip_delay": true
  },
  "tenant": "ingen_isla_nublar"
}

Response

workflow_run_idstring uuid required

This value allows you to track individual messages associated with this trigger request.

Example response

{
  "workflow_run_id": "123e4567-e89b-12d3-a456-426614174000"
}

Changes

Sep 15, 20266f88a4142e34 Revision changes
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
- info
  added the new optional request property //////////
Aug 13, 2026fcba175ebc76 Revision changes
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the ////// request property type changed from boolean to no type
- breaking
  the ////// request property type changed from boolean to no type
- breaking
  the ////// request property type changed from boolean to no type
- breaking
  the ////// request property type changed from boolean to no type
- breaking
  the ////// request property type changed from boolean to no type
- breaking
  the ////// request property type changed from boolean to no type
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list
- info
  added subschema #1 subschema #3 to the ////// request property anyOf list

Operation history (12 revisions)