Sources in Knock

With Knock sources, you can integrate customer data platforms (CDPs) such as Segment and Rudderstack or reverse ETL platforms such as Hightouch and Census with Knock to trigger notification workflows, identify users, and automate other actions.

In general, each platform we support can do the following within Knock:

• Trigger workflows
• Identify (and update) users

Here are a few reasons why you might want to integrate a source with Knock to power your notification system, rather than making direct calls to the Knock API:

• Minimize engineering customization. If you already identify and track users with a customer data platform (CDP), you can import your users and events in minutes. Once your CDP is integrated with Knock, you can easily build notification workflows without needing time from engineering.
• Ensure consistency. CDPs make it easy to keep customer data synchronized between services, including Knock. Email, name, and other user trait updates can flow seamlessly into Knock without any engineering work.

Concepts

Sources

A source is any platform that can pass event and/or user data into Knock. These can be CDPs (such as Segment and Rudderstack) or reverse ETLs (such as Hightouch and Census.) The incoming events from these services can be used to orchestrate actions in Knock such as creating/updating users and triggering workflows.

Knock currently supports the following sources:

• Segment
• Rudderstack
• Jitsu
• Freshpaint
• Hightouch
• Census
• Polytomic
• HTTP (a generic HTTP endpoint for accepting events)

Need us to support another platform? Let us know!

You can configure sources from the Integrations > Sources page for your account. Initial creation of a source is managed at the account-level of your Knock account, though you'll configure any specific events and their workflow triggers within your Knock environments.

Per-environment source configuration

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

Events

Knock tracks every event sent from a source. Although each source has its own event format, Knock will translate the incoming events from each source 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, e.g. for a Segment track with some associated properties, Knock would use those properties to set the data field for the event.
• event. The original event, as originally received by Knock.

Workflow triggers

When Knock receives an event from an integration source, it will check for any workflows that have been configured to be triggered by that event in that environment.

You can have any number of workflows triggered by each event. If there is no workflow configured to be triggered by that event, the event is logged but no action is taken.

After configuring a source in Knock and in the source itself (e.g. adding Knock as a destination in your CDP), events will start to flow into your Knock environment.

You can then select an event and connect it to a workflow as its trigger.

Identifying users

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

Note that Knock will correctly map name, email, avatar, and phone properties from Segment and Rudderstack identify calls into Knock's user data model. All other tracked properties of a user will be stored as additional custom properties on the Knock user object, and can be used in templates and other parts of Knock that rely on user properties.

Inline identify users in a source event

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 guide on identifying recipients.

Event idempotency

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

Configuring idempotency checks

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 will use 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 will be processed like normal.

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

How Knock handles idempotent events

When Knock executes a source event with an idempotency key, it will first check to see if a preceding execution should be replayed. Knock will find 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 will execute your event like normal and record 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 will only record 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.

Logging

Event logs

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

Action logs

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