HTTP source

The HTTP source enables you to receive webhook events from any service that can make HTTP callbacks and map those events to actions inside Knock. Use it when you need to connect a service that Knock does not yet offer a pre-built integration for, or when you want to send events from your own internal tools and applications.

Custom webhooks are the right choice when:

• The service you want to connect does not have a pre-built Knock source integration.
• You are sending events from an internal tool, custom application, or microservice.
• You need full control over event type identification and field mapping.

For services with pre-built integrations (Stripe, Clerk, WorkOS, Supabase, PostHog), use those dedicated source pages instead. They provide automatic signature verification and pre-configured event types.

When Knock receives an event from a custom webhook, it needs to know how to identify the event type from the payload. You configure this by specifying a key path that tells Knock where to find the event type value in the JSON body.

For example, if your service sends payloads like:

You would set the key path to event_type so Knock can identify this as a task.completed event.

You can also specify an optional timestamp path if your payloads include a timestamp field that you want Knock to use as the event time instead of the ingestion time.

After events start flowing into Knock, you can configure what action Knock should take when it receives each event type. From the source environment configuration page:

1. Select an event type from the list of received events.
2. Click "Create action mapping" to add a new mapping.
3. Choose the action to execute (trigger workflow, identify user, set object, and so on). See the available actions in the overview for the full list.
4. Map fields from the incoming payload to the parameters the action requires.

You can create multiple action mappings for a single event type. For example, a customer.created event could both identify a user and trigger a welcome workflow.

Field mappings use dot-notation paths to extract values from the incoming JSON payload and map them to the parameters each action expects.

Given a payload like:

You could create the following mappings when triggering a workflow:

Payload path	Maps to
data.assigned_to	Recipients
data.task_id	data.task_id
data.project.name	data.project_name

A few things to keep in mind:

• Paths are case-sensitive and follow the structure of your JSON payload.
• You can map a single event to multiple action parameters.
• Knock validates that required fields are populated before executing the action. If a required field is missing, the action is skipped and an error appears in the action log.

Suppose you have a task management app that sends a webhook when a task is assigned. The payload looks like this:

To trigger a notification workflow when a task is assigned:

1. Set the key path to event_type.
2. Wait for a task.assigned event to arrive (or send a test event).
3. Create an action mapping that triggers your task-assigned workflow.
4. Map data.assigned_to to Recipients and data.assigned_by to Actor.
5. Map data.task_id and data.title to workflow data fields so you can reference them in your notification templates.

You can see a log of all events received per source under Integrations > Sources in the Knock dashboard on the "Logs" page for your configured source. Common issues to look for:

• Missing fields. A required field path does not exist in the incoming payload. Check that the dot-notation path matches your payload structure.
• Invalid paths. The key path for event type identification does not resolve to a value. Verify the path against a sample payload.
• Type mismatches. A field value does not match the expected type (for example, passing a string where a user ID array is expected).

---

The legacy HTTP source creates a generic event ingestion endpoint that accepts events structured according to the Segment track spec. The events you stream into the HTTP source can be used to trigger Knock notification workflows.

Knock can receive any structured event data via the legacy HTTP source, as long as you format the payload as JSON and make an HTTP request from the service that produces or consumes events.

To get started you can create a new HTTP source by going to Integrations > Sources under your account settings and clicking "Create source." You'll have the opportunity to name the HTTP source and give it a description.

Once your source is created, you'll have a unique ingestion endpoint per environment to send events to. You can get each environment's endpoint by clicking the "Copy webhook destination URL" button.

To start sending events to Knock, structure a JSON payload that matches the event schema below and submit it via a POST request to the ingestion endpoint. A well-formed event payload receives a 204 response code.

You also need to send the following headers with your request:

You need to send a single event at a time. There is no batch event ingestion endpoint.

Your events must be structured as JSON with the following schema:

Name	Type	Description
type	string (required)	The type of event to send. Must be set to track.
event	string (required)	The name of the event you're sending to Knock.
properties	map	A set of properties associated with the event.
userId	string	An optional userId to be used as the recipient or actor for the triggered workflow.
messageId	string	An optional unique identifier for the event message, to be used as a deduplication key.
timestamp	string	An optional ISO-8601 timestamp indicating when the event occurred. If omitted, defaults to the time of ingestion.

Received events can be configured as workflow triggers directly in the workflow editor. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you can select the event and map its properties into the data the workflow needs.

Read more on configuring workflow triggers

Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, go to the trigger page and toggle its status to "Inactive." This disables that trigger for the current environment only. When you're ready to trigger the workflow again, set it back to "Active."

When creating workflow triggers from your events, you can optionally configure the schema mapping Knock uses to map your event properties into the corresponding workflow trigger properties.

To target any items under the properties key, prefix the schema mapping with data.propertyKey. As an example, if you have a property properties.recipientId you would map this as data.recipientId.

You can see a log of all events received per source under Integrations > Sources in the Knock dashboard under the "Logs" page for your configured source. You can also see any workflow triggers that were configured as part of the event ingestion, and any workflow runs that were triggered.