Wait for event function

A wait for event function pauses a workflow until a matching source event is received, or until a configured wait time expires. Use it when the next step in your workflow should depend on something that happens outside Knock — such as a payment completing, a user finishing onboarding in another system, or a webhook firing from a connected integration.

When a workflow run reaches a wait for event step, Knock pauses execution and registers a durable wait for the configured source event. The workflow stays paused until one of the following happens:

1. A matching event is received. Knock evaluates the event against your match conditions. If the event passes, Knock applies your On match action and resumes the workflow (or halts it, depending on your configuration).
2. The wait time expires. If no matching event arrives before the wait time ends, Knock applies your After wait time action.

While the workflow is paused, no downstream steps execute. This makes the wait for event function useful for coordinating notifications with external product activity without building polling or state management in your application.

When you add a wait for event step in the workflow builder, you configure the following settings.

Select the integration source event to wait for. Knock matches incoming events from your connected sources against this selection. The event is identified by its event key and integration source key, which remain stable when you promote workflows between environments.

Your Knock environment must have at least one configured source that has received the event you want to wait for.

Match conditions filter incoming source events before the workflow resumes. Knock evaluates each candidate event against these conditions. If an event does not pass, the workflow keeps waiting until a matching event arrives or the wait time expires.

You can build match conditions using the same conditions builder used elsewhere in Knock. The following variable namespaces are available:

Namespace	Description
event.*	The awaited event payload. Use this namespace for fields on the incoming source event.
recipient.*	The workflow recipient.
data.*	The original workflow trigger payload.
vars.*	Environment variables.
tenant.*	The tenant associated with the workflow run.
Audience membership	Check whether the recipient belongs to an audience.
refs.*	Message status from preceding channel steps in the workflow run.

When a source event includes a user_id, Knock scopes matching to the workflow recipient for that run. Events without a recipient association can still match waits that are registered without recipient scoping.

Controls what happens when a matching event is received before the wait time expires:

• Continue workflow. Resume execution and proceed to the next step. This is the default.
• Halt workflow. Cancel the workflow run. Use this when the awaited event means later steps should not execute — for example, canceling a reminder workflow when a user completes the action you were going to remind them about.

How long Knock waits for a matching event before timing out. The dashboard default is 15 minutes. You can configure the duration in seconds, minutes, hours, days, or weeks.

A workflow can wait for a maximum of 30 days.

Controls what happens when the wait time expires before a matching event arrives:

• Halt workflow. Cancel the workflow run. This is the default.
• Continue workflow. Resume execution and proceed to the next step.

Like other workflow steps, a wait for event step supports step conditions that determine whether the step executes at all when the workflow run reaches it. Step conditions are evaluated when the step runs, not when an external event arrives.

When a wait for event step resumes on a Continue workflow path, it writes output under refs.<step_ref> that downstream steps can reference:

Property	Type	Description
matched	boolean	true when a matching event claimed the wait; false when the wait timed out.
signal_variables	object	The payload from the matched source event. An empty object on timeout.

Use refs.<step_ref>.matched in a downstream branch function to run different logic depending on whether the event arrived in time. Use refs.<step_ref>.signal_variables to access fields from the matched event payload in conditions or templates.

Trigger a workflow when a user starts a flow, add a wait for event step that listens for a completion event from your product analytics or CDP source, then send a follow-up notification only if the user does not complete the action within your wait window.

Pair this with On match: Halt workflow and After wait time: Continue workflow so the workflow proceeds to your reminder step only when the completion event does not arrive in time.

Pause a workflow after an initial notification and wait for a webhook event — such as invoice.paid from Stripe — before sending a confirmation message. Add match conditions on event.* fields to narrow which events resume the workflow.

After the wait resolves, use a branch step with conditions on refs.<step_ref>.signal_variables to send different notifications based on data in the matched event.

Both wait for event and delay functions pause a workflow, but they differ in what resumes execution:

	Wait for event	Delay
Resumes when	A matching source event arrives, or the wait time expires	The configured interval or timestamp elapses
Depends on external activity	Yes	No
Match conditions	Yes	No

Use a delay when you need to wait a fixed amount of time. Use wait for event when the workflow should react to something happening in an external system.

Workflow runs paused at a wait for event step can be canceled using the workflow cancellation API, the same as runs paused at a delay, batch, or fetch step. Provide a cancellation_key when you trigger the workflow, then call the cancel endpoint with the same key.

Canceling a paused workflow deletes the scheduled resume job and marks the durable wait as canceled. No downstream steps execute after cancellation.

You can inspect wait for event execution in the workflow debugger. For each workflow run, the debugger shows:

• Whether the workflow is still waiting for an event, or which event was received
• When the wait expires or expired
• Match condition evaluations for candidate events, including the result of each evaluation

When match conditions reject an incoming event, Knock logs a wait_conditions_evaluated event on the workflow run so you can see why the event did not resume the workflow.