Docs
/
/
Contact supportLog inGet started
Overview
Client libraries
API keys
Authentication
Rate limits
Batch rate limits
Idempotent requests
Data retention
Bulk endpoints
Trigger data filtering
Pagination
Errors
Common error codes
Overview
Trigger workflow
Cancel workflow
Get startedLog inContact support
Platform
Integrations
In-app UI
API reference
CLI reference
Management API
Developer tools
Tutorials

Workflows API reference

Complete reference documentation for the Workflows resource.

Workflows

#

A Workflow orchestrates the delivery of messages to your end users. When you configure a workflow you'll determine which channels its messages should route to, what those messages should look like on each channel, as well as any functions—batch, throttle, delay—you want applied to the messages prior to delivery.

To send notifications, you’ll trigger your workflows. A workflow is triggered by a trigger call, typically when an event occurs in your product that you want your users to know about (e.g. a new comment.)

Endpoints

POST/v1/workflows/{key}/trigger
POST/v1/workflows/{key}/cancel
Idempotent

Trigger workflow

#

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.

Endpoint

POST/v1/workflows/{key}/trigger
Tier 5

Path parameters

key
string

Key of the workflow to trigger.

Request body

actor
RecipientRequest

A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.

cancellation_key
string

An optional 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.

data
object(any)

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.

recipients
RecipientRequest[]
Required

The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.

tenant
InlineTenantRequest

The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.

Returns

TriggerWorkflowResponse

The response from triggering a workflow.

workflow_run_id
string(uuid)

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

Cancel workflow

#

When invoked for a workflow using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally be provided one or more recipients to scope the request to.

Endpoint

POST/v1/workflows/{key}/cancel
Tier 5

Path parameters

key
string

The key of the workflow to cancel.

Request body

cancellation_key
string
Required

An optional 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.

recipients
RecipientReference[]

A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.

Returns

204 No Content
New chat