---
title: Triggering workflows via the API
description: Learn more about how to trigger cross-channel notification workflows in Knock via the API.
tags: ["trigger", "notify", "data", "actor"]
section: Send notifications
---

The trigger API endpoint executes workflows for your recipients. When you call the `trigger` endpoint, Knock runs your specified [Recipients](/concepts/recipients) and `data` through the workflow.

<MultiLangCodeBlock
  snippet="workflows.trigger"
  title="Trigger a Knock workflow"
/>

Learn more about triggering workflows in [our API reference](/api-reference/workflows).

## Trigger payload

| Property         | Type                  | Description                                                                                                 |
| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| key\*            | string                | The human-readable key of the workflow from the Knock dashboard                                             |
| actor            | RecipientIdentifier   | An identifier of who or what performed this action (optional)                                               |
| recipients\*     | RecipientIdentifier[] | One or more recipient references of who/what to notify for this workflow                                    |
| data             | map                   | A map of properties that are required in the templates in this workflow                                     |
| cancellation_key | string                | A unique identifier to reference the workflow when canceling                                                |
| tenant           | string                | An optional identifier of the owning tenant object for the notifications generated during this workflow run |
| settings         | map                   | An optional map of settings that control how this workflow run is executed                                  |

## Recipient identifiers

When you want to identify a recipient in a workflow, either as an actor or as a recipient you can send either:

- A string indicating a user that you have previously identified to Knock (e.g. `user-1`).
- A reference of an object that you have previously set within Knock (e.g. `{ id: "project-1", collection: "projects" }`).
- A complete `Recipient`, to be identified inline during the workflow execution.

## Response

Triggering a workflow will always return a unique UUID v4 representing the workflow run.

```json title="Trigger workflow response"
{
  "workflow_run_id": "05f8a70d-e42a-46dc-86fa-aada5752f6cf"
}
```

<br />

<Callout
  type="info"
  title="Note:"
  style={{ marginTop: "0" }}
  text={
    <>
      a workflow run ID is a unique identifier that represents the workflow run
      for all recipients of the workflow. Each individual in the workflow run
      will have a unique workflow recipient run ID, which is derived from the
      workflow run id.
    </>
  }
/>

## Passing data to your trigger

Pass schema data required by the workflow in your `trigger` call. The payload must be a valid JSON object. 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](/developer-tools/api-logs#log-truncation) in your logs.

The workflow builder determines which data keys are required.

<Callout
  type="info"
  text={
    <>
      For more information on validating trigger data and working with JSON
      schemas, see our documentation on{" "}
      <a href="/developer-tools/validating-trigger-data">
        validating trigger data
      </a>
      .
    </>
  }
/>

## Attributing the action to a user or object

Pass an `actor` in your trigger call to attribute the workflow run to a specific user or object.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-actor"
  title="Triggering a Knock workflow with an actor"
/>

Calling a workflow trigger with an actor:

- Records who triggered the workflow
- Links the actor to any in-app feed messages
- Includes the actor in batch steps via the `actors` key
- Excludes the actor from notifications when they are a [subscriber](/concepts/subscriptions) to an Object recipient

## Generating a cancellation key

Include a `cancellation_key` in your `trigger` call to enable workflow cancellation.

You can read more about canceling workflows [in our documentation](/send-notifications/canceling-workflows).

The key should uniquely identify the workflow run you want to cancel. We recommend using:

- A UUID v4
- A hash of relevant workflow data
- A timestamp combined with recipient and workflow identifiers

## Deduplicating workflow runs

You can include an optional `Idempotency-Key` header in your trigger call to safely retry requests without creating duplicate workflow runs. This helps prevent users from receiving duplicate messages if the same trigger is accidentally sent more than once. If a request is retried with the same idempotency key within 24 hours, Knock will return the same response as the original request. Idempotent requests are expected to be identical. To prevent accidental misuse, Knock returns an error when incoming parameters don't match those from the original request.

You can read more about how Knock handles idempotent requests in [our API reference](/api-reference/overview/idempotent-requests).

## Identifying recipients inline

You can pass a complete `Recipient` entity to the `recipients` or `actor` property when triggering a workflow. When passing the recipient, the recipients will be guaranteed to be identified **before** the workflow is triggered for the recipient with the properties passed in.

| Property        | Description                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `id`            | Required. An identifier for this user or object                                                        |
| `collection`    | Required when identifying an object. Indicates the collection the object belongs to                    |
| `channel_data`  | A dictionary containing a `channelId` key and a dictionary of channel data to be set for the recipient |
| `preferences`   | A dictionary containing a preference set ID key and a `PreferenceSet` object to set for the recipient  |
| `$trigger_data` | Any recipient-specific trigger data to merge in with the `data` available on the workflow run          |
| \*              | An arbitrary set of key/value pairs to set for the recipient                                           |

```json title="Example inline recipient definition"
{
  "id": "user-1",
  "name": "Jean Luc-Picard",
  "email": "jpicard@starfleet.org",
  "channel_data": {
    "4672d685-c586-4ec6-ad88-52185262af97": {
      "tokens": ["apns-push-token"]
    }
  },
  "preferences": {
    "default": {
      "channel_types": {
        "email": true,
        "sms": false
      }
    }
  }
}
```

## Per-recipient trigger data

Per-recipient data is useful when you want to notify an array of recipients with a single trigger, but include custom data per-recipient.

You can pass per-recipient data to your trigger by passing a dictionary of data under the `$trigger_data` property for each recipient. Any data provided under this property will be merged with the data passed in the `data` property to produce the final data available for the recipient's workflow run.

```json title="Example per-recipient data"
{
  "data": {
    "alert_type": "security_breach",
    "location": "Visitor Center"
  },
  "recipients": [
    {
      "id": "jhammond",
      "name": "John Hammond",
      "$trigger_data": {
        "role": "Park Owner",
        "dashboard_url": "https://jurassicpark.com/dashboard/jhammond"
      }
    },
    {
      "id": "esattler",
      "name": "Ellie Sattler",
      "$trigger_data": {
        "role": "Paleobotanist",
        "dashboard_url": "https://jurassicpark.com/dashboard/esattler"
      }
    },
    {
      "id": "dnedry",
      "name": "Dennis Nedry",
      "$trigger_data": {
        "role": "Systems Programmer",
        "dashboard_url": "https://jurassicpark.com/dashboard/dnedry"
      }
    }
  ]
}
```

For example, the final merged data available to Ellie Sattler's workflow run would be:

```json title="Final merged data for esattler"
{
  "alert_type": "security_breach",
  "location": "Visitor Center",
  "role": "Paleobotanist",
  "dashboard_url": "https://jurassicpark.com/dashboard/esattler"
}
```

## Multi-tenancy in notifications

You can optionally pass a `tenant` to your `trigger` call. For products where users belong to multiple tenants, this scopes the workflow run to the account, organization, or workspace where the event occurred.

The tenant scopes in-app feed messages and controls [tenant-scoped chat connection selection](/managing-recipients/setting-channel-data#scope-chat-connections-by-tenant). When a Slack, Microsoft Teams, or Discord recipient has connections tagged with `knock_tenant_id`, Knock uses connections that match the `tenant` in the trigger. If none match, Knock falls back to untagged connections.

The `knock_tenant_id` on a connection does not set the workflow run's tenant. You must pass the tenant in the trigger for connection selection to apply.

You can read more about [supporting multi-tenancy](/concepts/tenants).

## Testing workflows with trigger settings

You can pass an optional `settings` object in your `trigger` call to control how the workflow run is executed. These settings are useful when testing a workflow, and mirror the options available in the [workflow test runner](/send-notifications/testing-workflows#test-run-settings).

| Property     | Type    | Description                                                                                                                                                                                                                                                   |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sandbox_mode | boolean | When `true`, all messages in the workflow run are forced to send in [sandbox mode](/integrations/overview#sandbox-mode), overriding the per-channel configuration. Messages are generated but not delivered to the underlying providers. Defaults to `false`. |
| skip_delay   | boolean | When `true`, all [delay steps](/designing-workflows/delay-function) in the workflow are force skipped, so the run executes straight through without waiting. Defaults to `false`.                                                                             |

```json title="Example trigger with settings"
{
  "recipients": ["user-1"],
  "data": {
    "message": "Life finds a way"
  },
  "settings": {
    "sandbox_mode": true,
    "skip_delay": true
  }
}
```

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I trigger a workflow for a single recipient?" anchorSlug="faq-trigger-workflow-single-recipient">
    You can trigger a workflow for a single recipient by passing a single
    recipient identifier to the `recipients` property in your trigger call.
  </Accordion>
  <Accordion title="How do I trigger a workflow for multiple recipients?" anchorSlug="faq-trigger-workflow-multiple-recipients">
    You can trigger a workflow for multiple recipients by passing an array of
    recipient identifiers to the `recipients` property in your trigger call.
  </Accordion>
  <Accordion title="How do I trigger a workflow for an object?" anchorSlug="faq-trigger-workflow-for-object">
    You can trigger a workflow for an object by passing an object identifier to
    the `recipients` property in your trigger call.

    An object identifier looks like:

    ```json
    {
      "id": "project-1",
      "collection": "projects"
    }
    ```

  </Accordion>
  <Accordion title="How do I trigger a workflow for the subscribers of an object?" anchorSlug="faq-trigger-workflow-object-subscribers">
    You can trigger a workflow for the subscribers of an object by passing an object identifier to the `recipients` property in your trigger call. Knock will automatically create a workflow run for the object itself and for each subscriber of the object.

    <MultiLangCodeBlock
      snippet="workflows.trigger-with-object-as-recipient"
      title="Workflow trigger with an object as a recipient"
    />

  </Accordion>
  <Accordion title="How do I trigger a workflow for an audience?" anchorSlug="faq-trigger-workflow-for-audience">
    It's not yet possible to trigger a workflow for an audience via the API. If you're looking to trigger a workflow for a specific audience, please get in touch with us. We're currently considering how to best support this use case and would love to discuss your specific needs.
  </Accordion>
  <Accordion title="What's the maximum number of recipients I can trigger a workflow for?" anchorSlug="faq-max-recipients-per-workflow-trigger">
    You can trigger a workflow for up to 1000 recipients at a time. If you need to manage a larger list of recipients, you might want to consider using our [subscriptions feature](/concepts/subscriptions) to have Knock manage the set of recipients who need to be notified instead.
  </Accordion>
  <Accordion title="Can I bulk trigger workflows?" anchorSlug="faq-bulk-trigger-workflows">
    It's not currently possible to issue bulk trigger requests to the API. If you need to trigger workflows for multiple recipients with per-recipient data, you can pass per-recipient trigger data.
  </Accordion>
  <Accordion title="How do I cancel a workflow run?" anchorSlug="faq-cancel-workflow-run">
    You can cancel a workflow run by calling the `cancel` endpoint.

    <MultiLangCodeBlock
      snippet="workflows.cancel"
      title="Cancel a workflow run"
    />

  </Accordion>
  <Accordion title="Can I validate the data I'm passing to a workflow trigger?" anchorSlug="faq-validate-workflow-trigger-data">
    Yes, you can [validate the data you're passing to a workflow trigger](/developer-tools/validating-trigger-data) by
    providing a JSON schema in your workflow trigger step.
  </Accordion>
  <Accordion title="Can I generate types for my workflow triggers?" anchorSlug="faq-generate-types-for-workflow-triggers">
    Yes, you can [generate types for your workflow triggers](/developer-tools/type-safety) by providing a trigger data schema in your workflow trigger step.
  </Accordion>
</AccordionGroup>
