Sources in Knock

Sources connect external services to Knock so that events from those services can drive actions such as triggering workflows, identifying users, and managing objects and tenants. Knock supports two approaches for ingesting events from external services:

• Incoming webhooks. Receive webhook events from services like Stripe, Clerk, or your own applications and map them to actions in Knock. Knock provides pre-built integrations for popular services and a custom webhook option for any service that can send HTTP callbacks.
• CDP and reverse ETL integrations. Pipe track and identify events from platforms like Segment, RudderStack, Hightouch, and Census into Knock to trigger workflows and keep user data in sync.

A source is any platform that can pass event or user data into Knock. Sources fall into two categories:

• Incoming webhook sources. Services that send webhook callbacks to Knock when events occur (for example, Stripe sending an invoice.paid event). Knock verifies the payload, parses the event type, and executes the actions you configure.
• CDP and reverse ETL sources. Platforms such as Segment, RudderStack, Hightouch, and Census that forward track and identify events to Knock.

Source	Description
Clerk	Auth and user management events
PostHog	Product analytics action and event webhooks
Stripe	Payment and subscription lifecycle events
Supabase	Database webhook events
WorkOS	Directory sync and SSO events
HTTP	Custom webhooks from any service

Source	Description
Segment	Customer data platform
RudderStack	Customer data platform
Hightouch	Reverse ETL
Census	Reverse ETL
Polytomic	Reverse ETL
Jitsu	Open-source data pipeline
Freshpaint	Healthcare-focused CDP

Need us to support another platform? Let us know.

You can configure sources from the Integrations > Sources page in your account settings. Initial creation of a source is managed at the account level of your Knock account, though you configure specific events and their actions within your Knock environments.

Each source has a unique configuration for every Knock environment in your account. This makes it possible to connect your development source environment to your Knock development environment. If you click on a source, you will see each environment configuration for that source.

Event logs show the contents of each event sent into Knock.

Action logs describe what (if any) action Knock took after receiving an event. Action logs are a helpful starting point when troubleshooting workflows or auditing actions Knock has taken for any given event.

Incoming webhook sources let you receive webhook events from external services and map them to actions inside Knock. When Knock receives a webhook event it verifies the payload signature, identifies the event type, and executes the actions you have configured for that event.

1. Create the source. Add an incoming webhook source on the Integrations > Sources page in the Knock dashboard. Knock provides a unique webhook URL for each environment.
2. Configure the provider. Copy the webhook URL into the external service's webhook settings. For pre-built integrations, paste the signing secret from the provider into Knock so payloads can be verified.
3. Receive events. When the external service sends a webhook, Knock verifies the signature (if applicable), parses the event type, and logs the event.
4. Map events to actions. For each event type, configure one or more actions that Knock should execute.

Knock offers pre-built integrations for popular services. These integrations come with signature verification and pre-configured event types ready to use. The following pre-built incoming webhook sources are available:

• Clerk
• PostHog
• Stripe
• Supabase
• WorkOS

For any service that can send HTTP callbacks, you can use the HTTP source to create a custom webhook integration. Custom webhooks require you to define event type identification and field mappings yourself.

When an incoming webhook event is received, you can configure Knock to execute any of the following actions:

Action	Description
Trigger workflow	Start a workflow run for one or more recipients
Cancel workflow	Cancel an in-progress workflow run
Identify user	Create or update a user in Knock
Subscribe user	Add a user to an object's subscribers list
Unsubscribe user	Remove a user from an object's subscribers list
Set object	Create or update an object
Delete object	Remove an object
Set tenant	Create or update a tenant
Delete tenant	Remove a tenant
Add audience member	Add a member to an audience
Remove audience member	Remove a member from an audience

After events start flowing into Knock you can configure mappings that tell Knock which action to run and how to populate its parameters. Mappings use dot-notation paths to extract values from the incoming payload and map them to the fields required by each action.

For example, given a payload like:

You could map data.object.customer to the recipients field when triggering a workflow.

For full details on configuring custom event types and field mappings, see the HTTP source page.

CDP and reverse ETL sources forward track and identify events from platforms like Segment, RudderStack, Hightouch, and Census into Knock.

Knock tracks every event sent from a source. Although each source has its own event format, Knock translates incoming events into a common format that includes the following fields:

• user_id. The ID of the user performing a given action (may not be set if a user has not been identified yet).
• data. The primary contents of the event. For example, for a Segment track call with associated properties, Knock uses those properties to set the data field.
• event. The original event, as originally received by Knock.

When Knock receives an event from a CDP or reverse ETL source, it checks for any workflows configured to be triggered by that event in that environment.

You can have any number of workflows triggered by each event. If no workflow is configured for an event, the event is logged but no action is taken.

After configuring a source in Knock and in the source itself (for example, adding Knock as a destination in your CDP), events start flowing into your Knock environment. You can then select an event and connect it to a workflow as its trigger.

For sources that support identifying users (such as Segment or RudderStack with their identify calls), each environment configuration includes a setting to enable or disable user identification. After creating an integration source, enable identifying users for that environment.

Knock correctly maps name, email, avatar, and phone properties from Segment and RudderStack identify calls into the Knock user data model. All other tracked properties are stored as custom properties on the Knock user object and can be used in templates and other parts of Knock that rely on user properties.

In cases where you send a source event to Knock with recipients that may not yet have been identified into our system, it's good practice to inline identify your users. By inline identifying your users within your source events, you ensure that those users are identified in Knock when your event triggers a workflow.

As an example, take the user-signed-up event below. We're currently mapping the properties.recipients field to the recipients field of our workflow in Knock. If we send this event to Knock before the user with id sam10 has been identified, the user will not be notified.

To ensure that the user is notified, we'd change the id reference in recipients to a complete user object, as in the example below. This way Knock has all the information it needs to identify the user during workflow runtime.

You can learn more about inline identification in our documentation on identifying recipients.

By default, Knock processes every valid event received from your source. You can enable idempotency checks to deduplicate events that have already been received and processed. This is useful if you know your source may send duplicate events.

You can enable source event idempotency checks at any time from the "Settings" tab for your source environment configuration.

Once enabled, Knock will start parsing idempotency keys from your source events for use in deduplication checks. Knock uses an optional, unique attribute made available by your source provider. These attributes are:

• Segment. messageId
• RudderStack. messageId
• HTTP. messageId

Events without an idempotency key attribute are processed normally.

Your idempotency keys must be valid strings no more than 255 characters in length. If an invalid key is found, Knock still ingests your source event but will not attempt to execute your event idempotently. In addition, Knock drops the invalid idempotency key and you will not see it appear in your event logs.

When Knock executes a source event with an idempotency key, it first checks whether a preceding execution should be replayed. Knock finds a preceding execution if it is recorded within the idempotency window with the same:

• Idempotency key value
• Event type
• Integration source configuration
• Knock environment in your account

If no preceding execution is found, Knock executes your event normally and records that execution for future replay by the same idempotency key. However, if Knock fails to execute your source event, it will not record the execution. Knock only records successful event executions for idempotent replay.

If Knock replays an event via an idempotency check, you will still see an event log for that execution. However, the log will not have any actions associated and Knock will label it as idempotent.