Goals

A goal is a reusable, environment-scoped outcome with special business meaning that you want to measure. For example, you might define a "Customer activated" goal that completes when a user enters a paid-customers audience, or when Knock receives an order.completed event from a connected integration source.

Each goal has a condition that defines when the goal is met. When a recipient meets the goal condition, Knock records a completion. When that completion can be credited to a workflow, broadcast, or guide that has the goal attached, Knock also records an attribution to that resource on the completion.

Use goals to:

• Track outcome-based engagement with customer messaging, beyond opens and clicks.
• Measure how often an outcome happens and which messaging resource it should be attributed to.
• Give the Knock agent context about intent so it can propose messaging improvements against those outcomes.

A goal condition defines what outcome must happen for the goal to be completed. Knock evaluates goal conditions globally for a recipient when events happen in an environment, outside of a workflow or broadcast run. When a goal condition is met, Knock records a completion.

Supported event types include:

Event type	Description
Integration source	An event from a connected source, such as Segment, Stripe, PostHog, or a custom source.
Audience entry / exit	A recipient entering or leaving a dynamic audience. Static audiences are not supported.

For an integration source condition, you can add additional match filters based on event or recipient properties to refine the goal's completion criteria. Goals with audience conditions can be refined by adding additional conditions directly to the dynamic audience's definition. For supported operators, see the conditions docs.

Knock records a goal completion when it sees a recipient event that matches the goal's condition. The event must meet the following criteria to record a successful completion:

Event type	Completion criteria
Integration source	The configured source ingests an event that is associated with a recipient already stored in your Knock environment, and any optional match filters pass.
Audience entry / exit	The configured dynamic audience exists in the same environment, and the recipient entered or exited it.

When a goal is attached to a messaging resource like a workflow, broadcast, or guide, Knock attributes the goal's completion to the most recent message sent to the recipient from that attached resource.

If multiple resources are attached to a goal, Knock attributes a goal's completion to the resource that sent the most recent message. After an attributed completion, if a recipient meets the goal condition again before any additional messages have been sent, a new completion will be recorded without attribution. Subsequent messages from an attached resource make the next completion eligible for attribution again.

When you connect a goal to a messaging resource, you'll configure an attribution window. The window defines the number of days after a message is sent during which a completion can be credited to the resource; completions that occur after the window has elapsed will not be attributed. The attribution window defaults to 7 days, and can be set to any value between 1 and 30 days.

A guide's attribution window is measured from the first time a recipient sees the guide. For workflows and broadcasts, a window begins when a message is sent to a recipient. Each new message from a workflow or broadcast resets its attribution window.

The following scenarios use a "Project created" goal, which completes when Knock receives a project.created event for a recipient. The goal is attached to two resources: an onboarding email workflow with a 7-day attribution window, and a "create your first project" guide with a 30-day attribution window.

1. A new message resets the attribution window. The onboarding workflow emailed a user 8 days ago and again yesterday. The user first saw the guide 6 days ago. When the user creates a project today, the first email's window has closed, but yesterday's email started a new one, so both resources are within their windows. The workflow sent the most recent message, so Knock attributes the completion to the workflow.

2. The most recent message's attribution window has expired. The onboarding workflow emailed a user 8 days ago, and the user first saw the guide 10 days ago. Although the workflow sent the most recent message, its 7-day window has closed. The guide is still within its 30-day window, so Knock attributes the completion to the guide.

3. A message can only be attributed once. The onboarding workflow emails a user, and the user then creates two projects. Knock records two completions but attributes only the first one. The user's next completion can be attributed only after the workflow sends a new message.

To create a goal, navigate to the Goals page in the Knock dashboard and click "Create goal." Each goal has the following properties:

• Key. An immutable, environment-unique identifier for the goal.
• Name. A human-readable name for the goal.
• Description. Optional context about what the goal means for your business.
• Condition. The event that must occur for Knock to record a completion. See Goal conditions for more information.

Goals are scoped to an environment and cannot be created, updated, or attached to a messaging resource from a branch.

When you save a goal, Knock publishes it and measurement starts immediately.

Integration source conditions require a recipient path to associate a completion with a recipient. The recipient path is the path on the incoming event that contains the Knock user ID. Source events contain a body and headers, so the path usually starts with body — for example, body.userId. Legacy Segment, RudderStack, and HTTP sources use the top-level userId instead.

Goals have a version history but do not use the full commit-and-promote model that other versioned resources use. Changes to a goal's title, description, or condition create a new version of the goal as soon as you save them.

Resources that are attached to a goal reference it by its key instead of a pinned version, so new completions are always evaluated against the current published version of a goal. Completions that have already occurred will continue to be associated with a goal after it is updated.

You can clone a goal into the current environment or another environment. The cloned goal's key and title default to {key}-copy and {name} (Copy), but you can update these values before completing the clone. Cloning copies the goal definition, but it does not copy which workflows, broadcasts, or guides reference the goal.

Goals are not promotable between environments. To use the same goal definition elsewhere, clone it to the desired environment.

To attach a goal to a messaging resource, open a workflow, broadcast, or guide in the dashboard. On the Overview tab, select your goal, set an attribution window, then commit or publish the resource.

The attached goal lives on the messaging resource's version. Attaching, detaching, or changing the attribution window creates a new version of that workflow, broadcast, or guide, and follows that resource's commit model.

If your attached resource follows the commit-and-promote model, be sure to clone the goal into the destination environment(s) with the same key before you promote the messaging resource. The goal's key must be consistent across environments to attribute completions to the correct goal.

While there is no limit to the number of resources that can be attached to a single goal, each messaging resource can have at most one attached goal.

Archiving a goal removes it in every environment that has a goal with that key. Knock stops calculating new completions and attributions, but retains historical goal versions and completions. This action is permanent.

You should detach a goal from every resource that uses it before you attempt to archive it. Knock will refuse the archive if the goal remains attached to a resource.

Open a goal on the Goals page to see:

• Overview. A time series of completions for a selected range, including how many of those completions are attributed to an attached resource, with totals and a completion rate. Knock calculates the completion rate by dividing attributed completions by the count of unique recipients in that range.
• Completions log. A paginated list of individual completions for the same range as the overview. Each row includes the recipient, completion time, triggering event, and (when attributed) the winning messaging resource.

The Knock agent can propose, create, update, and reuse goals when building or improving messaging. It can also attach a goal to a workflow, broadcast, or guide. The agent cannot archive or clone a goal. Goal context helps the agent reason about what your messaging is trying to accomplish so that it can help you make improvements.

You can create, update, clone, archive, and attach goals to messaging resources programmatically with the Management API.

Goal upserts publish on save. Unlike workflows and guides, the goals upsert endpoint does not accept a commit parameter. Attached goals are stored on the associated workflow, broadcast, or guide as a goal_attachment.

The following are not currently supported by the goals feature:

• Using a goal completion to cancel an in-flight workflow run.
• Goal conditions based on updates to recipient properties.
• Goal conditions based on tenant properties.
• Attaching more than one goal to a single messaging resource.
• Promoting goals between environments (clone a goal instead).
• Creating, editing, or attaching goals on a branch.
• Managing goals with the Knock CLI.