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:

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 mappings to your notification workflows within your Knock environments.

A screenshot of where to find the Integrations - Sources page for your account

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.

A view of the environment configurations for a source in a Knock account

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.

Event-action mappings

When a source sends an event to a Knock environment, Knock will match that event with any configured event-action mappings in that environment.

You can have any number of mappings for each event (e.g. if the same event should trigger more than one workflow). If there is no mapping matching 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 the event you want to trigger actions in Knock, and configure it accordingly.

🚨
For workflow trigger action mappings, no more than 1000 recipients can be included in each event. If you exceed this limit, Knock will not process your action mappings and instead generate an error log.

If you need to manage a large list of recipients you might want to consider using our subscriptions feature to have Knock manage the set of recipients who need to be notified instead.

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.

🚨
Remember: if you send Knock a source event that includes a recipient that has not yet been identified in Knock, our system will not generate a workflow run for that user.

For use cases such as new signup events, where events will often reach Knock before identify calls, consider inline identification of users in your source events.

Inline identify users in a source event

☝️
Note: Inline identification is not supported by our workflow test runner, which can only trigger test runs for existing users. To test inline identification with a source event, you should send a test event from your configured source.

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.

💡
The default idempotency window for Knock Sources is 24 hours. If you're interested in configuring a different idempotency window for your account, please contact us at support@knock.app.

Configuring idempotency checks

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

A screenshot of where to configure idempotency for your Source.

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

⚠️
Data subject to retention policy enforcement. See the data retention docs for more details on how Knock enforces this policy.

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.

←Overview
Segment→