Event streams

An event stream source sends Knock an event each time something happens in another service, such as a Stripe invoice being paid or a Segment identify call. You choose which action Knock runs for each type of event.

Incoming webhooks, CDPs, and custom sources are event streams. See the sources overview for the full list and how to add one.

When a source 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, a Stripe invoice.paid event includes nested data about the invoice and customer:

You could map data.object.customer to the recipients field and data.object to the data field when triggering a workflow, giving your templates access to the invoice amount, currency, and subscription details.

If a single event type has multiple action mappings, Knock executes them in a fixed priority order based on action type, not the order in which you create mappings in the dashboard.

1. users_identify
2. users_delete
3. objects_set
4. objects_delete
5. tenants_set
6. tenants_delete
7. objects_subscribe
8. objects_unsubscribe
9. audiences_add_member
10. audiences_remove_member
11. workflows_trigger

This ordering is consistent across incoming webhook sources, including custom sources.

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

In some cases, you may need to debug source event connections to ensure your integration is sending the correct payloads to Knock.

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.

Before Knock stores these logs, it replaces the value of any filtered log key with [filtered]. This covers the event contents, preprocessing script output, action payload, and action result. Some keys that Knock filters by default in other logs, such as email, stay visible here unless you add them.

Knock only filters the logged copy, so your actions still receive the full values. Action logs keep your field mappings as they are, since those values are paths and not event data.

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.

Idempotency configuration varies by source type. For pre-built webhook integrations, Knock auto-configures the idempotency key. For CDP sources and custom webhooks, you may need to enable idempotency and verify the key field. See your individual source page for setup details.

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.