From c9e8dd37126a1145e53409b8bb74c468c07c3f48 Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Wed, 24 Jun 2026 19:51:19 -0700 Subject: [PATCH 1/3] docs: document sandbox mode and skip delays for the workflow test runner Add docs for the new test runner settings and the matching settings.sandbox_mode and settings.skip_delay trigger options. Co-authored-by: Cursor --- .../send-notifications/testing-workflows.mdx | 9 ++++++++ .../triggering-workflows/api.mdx | 23 +++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/content/send-notifications/testing-workflows.mdx b/content/send-notifications/testing-workflows.mdx index aa348b088..be352324a 100644 --- a/content/send-notifications/testing-workflows.mdx +++ b/content/send-notifications/testing-workflows.mdx @@ -20,6 +20,15 @@ Two things to know about workflow test configuration: After clicking "Run test," you will see a confirmation and a link to see the log to review the output and what was sent. You can learn more about Knock logs and the debugger [here](/send-notifications/debugging-workflows). +### Test run settings + +The test runner includes a few settings that control how the workflow executes during a test run: + +- **Sandbox mode.** When enabled, all messages sent from the workflow are forced to send in [sandbox mode](/integrations/overview#sandbox-mode). Knock generates and previews the messages without delivering them to the underlying providers, regardless of how sandbox mode is configured on each channel. This is useful for testing a workflow end-to-end without sending real notifications to your recipients. +- **Skip delays.** When enabled, all [delay steps](/designing-workflows/delay-function) in the workflow are force skipped. The workflow runs straight through without waiting, which lets you verify the full execution path without waiting for delays to elapse. + +You can also apply both of these settings when [triggering a workflow via the API](/send-notifications/triggering-workflows/api#controlling-trigger-behavior-with-settings) using the `settings.sandbox_mode` and `settings.skip_delay` properties, which is useful when testing workflows programmatically. + Note that [trigger frequency](/send-notifications/triggering-workflows/overview#controlling-workflow-trigger-frequency) is not enforced during test runs. Settings like "once per recipient" are bypassed — each time you run a test, the workflow will execute for the selected recipient regardless of your frequency setting. To validate trigger frequency as it behaves in production, use the [trigger API](/send-notifications/triggering-workflows/api). You can also use the workflow test runner to run a test payload for a [source event trigger](/integrations/sources/overview#workflow-triggers). If your workflow is triggered by an event, you will automatically see a JSON payload of the last received event that you can use to run a test. You can edit this payload or click "Fetch the latest event" to get the most recent from your source. diff --git a/content/send-notifications/triggering-workflows/api.mdx b/content/send-notifications/triggering-workflows/api.mdx index 50a013454..054916eab 100644 --- a/content/send-notifications/triggering-workflows/api.mdx +++ b/content/send-notifications/triggering-workflows/api.mdx @@ -24,6 +24,7 @@ Learn more about triggering workflows in [our API reference](/api-reference/work | 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 @@ -207,6 +208,28 @@ tenants to which they belong in your product. You can read more about [supporting multi-tenancy in our documentation](/concepts/tenants). +## Controlling trigger behavior with 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 From b278b3d3f0237e94e45204f39c0af4906935094d Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Fri, 26 Jun 2026 18:08:17 -0400 Subject: [PATCH 2/3] chore: update --- content/send-notifications/triggering-workflows/api.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/send-notifications/triggering-workflows/api.mdx b/content/send-notifications/triggering-workflows/api.mdx index 054916eab..5a308880a 100644 --- a/content/send-notifications/triggering-workflows/api.mdx +++ b/content/send-notifications/triggering-workflows/api.mdx @@ -212,10 +212,10 @@ You can read more about [supporting multi-tenancy in our documentation](/concept 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 | -| ------------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| 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`. | +| 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" { From c27e5a52a950a905a32e693a7ad5802643300146 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 30 Jun 2026 14:35:28 +0000 Subject: [PATCH 3/3] docs: address review feedback on test runner settings - Move test run settings after the source event paragraph - Remove duplicate trigger API link on the testing page - Rename API settings section to clarify testing scope Co-authored-by: Chris Bell --- content/send-notifications/testing-workflows.mdx | 10 +++++----- .../send-notifications/triggering-workflows/api.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/send-notifications/testing-workflows.mdx b/content/send-notifications/testing-workflows.mdx index be352324a..19f6cbf7e 100644 --- a/content/send-notifications/testing-workflows.mdx +++ b/content/send-notifications/testing-workflows.mdx @@ -20,6 +20,10 @@ Two things to know about workflow test configuration: After clicking "Run test," you will see a confirmation and a link to see the log to review the output and what was sent. You can learn more about Knock logs and the debugger [here](/send-notifications/debugging-workflows). +Note that [trigger frequency](/send-notifications/triggering-workflows/overview#controlling-workflow-trigger-frequency) is not enforced during test runs. Settings like "once per recipient" are bypassed — each time you run a test, the workflow will execute for the selected recipient regardless of your frequency setting. To validate trigger frequency as it behaves in production, use the [trigger API](/send-notifications/triggering-workflows/api). + +You can also use the workflow test runner to run a test payload for a [source event trigger](/integrations/sources/overview#workflow-triggers). If your workflow is triggered by an event, you will automatically see a JSON payload of the last received event that you can use to run a test. You can edit this payload or click "Fetch the latest event" to get the most recent from your source. + ### Test run settings The test runner includes a few settings that control how the workflow executes during a test run: @@ -27,11 +31,7 @@ The test runner includes a few settings that control how the workflow executes d - **Sandbox mode.** When enabled, all messages sent from the workflow are forced to send in [sandbox mode](/integrations/overview#sandbox-mode). Knock generates and previews the messages without delivering them to the underlying providers, regardless of how sandbox mode is configured on each channel. This is useful for testing a workflow end-to-end without sending real notifications to your recipients. - **Skip delays.** When enabled, all [delay steps](/designing-workflows/delay-function) in the workflow are force skipped. The workflow runs straight through without waiting, which lets you verify the full execution path without waiting for delays to elapse. -You can also apply both of these settings when [triggering a workflow via the API](/send-notifications/triggering-workflows/api#controlling-trigger-behavior-with-settings) using the `settings.sandbox_mode` and `settings.skip_delay` properties, which is useful when testing workflows programmatically. - -Note that [trigger frequency](/send-notifications/triggering-workflows/overview#controlling-workflow-trigger-frequency) is not enforced during test runs. Settings like "once per recipient" are bypassed — each time you run a test, the workflow will execute for the selected recipient regardless of your frequency setting. To validate trigger frequency as it behaves in production, use the [trigger API](/send-notifications/triggering-workflows/api). - -You can also use the workflow test runner to run a test payload for a [source event trigger](/integrations/sources/overview#workflow-triggers). If your workflow is triggered by an event, you will automatically see a JSON payload of the last received event that you can use to run a test. You can edit this payload or click "Fetch the latest event" to get the most recent from your source. +You can also apply both of these settings when triggering a workflow via the API using the `settings.sandbox_mode` and `settings.skip_delay` properties, which is useful when testing workflows programmatically.