knocklabs · JEverhart383 · Mar 24, 2026
diff --git a/content/integrations/sources/catalog.mdx b/content/integrations/sources/catalog.mdx
@@ -0,0 +1,35 @@
+---
+title: Source catalog
+description: A quick comparison of all available Knock sources, their integration methods, and capabilities.
+section: Integrations > Sources
+layout: integrations
+---
+
+This page provides a quick reference for comparing the available Knock sources. Each source connects to Knock differently depending on the platform type and integration method, and supports a different set of capabilities.
+
+## Source comparison
+
+| Source | Platform type | Integration method | Identify users | Trigger workflows | Sync audiences | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+| [Segment](/integrations/sources/segment) | CDP | Webhook destination in Segment pointing to Knock source URL | Yes | Yes | No | GA |
+| [RudderStack](/integrations/sources/rudderstack) | CDP | Webhook destination in RudderStack pointing to Knock source URL | Yes | Yes | No | GA |
+| [Hightouch](/integrations/sources/hightouch) | Reverse ETL | HTTP request destination (Knock API calls) + Embedded destination (audiences) | Yes | Yes | Yes | GA |
+| [Census](/integrations/sources/census) | Reverse ETL | Custom destination API + HTTP request destination (Knock API calls) | Yes | Yes | Yes | GA |
+| [Polytomic](/integrations/sources/polytomic) | Reverse ETL | Downstream destination | Yes | Yes | No | Beta |
+| [Jitsu](/integrations/sources/jitsu) | CDP | Downstream destination | Yes | Yes | No | Beta |
+| [Freshpaint](/integrations/sources/freshpaint) | CDP | Downstream destination | Yes | Yes | No | Beta |
+| [HTTP](/integrations/sources/http) | Generic | Direct POST to Knock-provided ingestion endpoint | No | Yes | No | GA |
+
+## Integration methods explained
+
+There are a few different patterns for how sources connect to Knock. Understanding these can help you evaluate which source best fits your stack.
+
+- **Webhook destination.** Segment and RudderStack do not have first-party Knock integrations. Instead, you configure a webhook destination within those platforms that points to a Knock-provided source URL. Events (track and identify) flow through the webhook into Knock, where they appear as source events that can trigger workflows.
+
+- **HTTP request destination (Knock API calls).** Hightouch and Census can make direct HTTP requests to the Knock API as part of their sync process. This is how both platforms handle identifying users in Knock. For example, Hightouch uses its HTTP request destination to call `PUT /v1/users/{id}`, while Census uses its HTTP request destination to call `/users/bulk/identify`. This approach gives you fine-grained control over which Knock API endpoints the platform calls.
+
+- **Custom or embedded destination (audience syncs).** Hightouch and Census also offer a purpose-built integration path for syncing audiences into Knock. Hightouch uses an "Embedded Destination" and Census uses a "Custom Destination API," both of which connect to Knock-specific endpoints (e.g. `https://api.knock.app/v1/integrations/hightouch/embedded-destination`). These are simpler to configure than generic HTTP requests and support automatic add/remove of audience members.
+
+- **Direct HTTP endpoint.** The HTTP source provides a generic ingestion endpoint that you can POST structured JSON events to from any service. It only supports track events (no identify), making it the most flexible but also the most manual option.
+
+- **Downstream destination (beta).** Jitsu, Freshpaint, and Polytomic are described as downstream destinations but are currently in beta with limited documentation. Contact [support@knock.app](mailto:support@knock.app) if you need early access.
diff --git a/content/integrations/sources/http.mdx b/content/integrations/sources/http.mdx
@@ -5,6 +5,26 @@ section: Integrations > Sources
 layout: integrations
 ---
 
+<Callout
+  type="warning"
+  title="Looking for incoming webhooks?"
+  text={
+    <>
+      The HTTP source is a legacy integration. For new integrations, we
+      recommend using{" "}
+      <a href="/integrations/sources/incoming-webhooks/overview">
+        incoming webhooks
+      </a>{" "}
+      instead, which support a broader set of actions, field mapping, and
+      webhook verification. You can use a{" "}
+      <a href="/integrations/sources/incoming-webhooks/custom-webhooks">
+        custom webhook
+      </a>{" "}
+      source to connect any service, or choose from our pre-built integrations.
+    </>
+  }
+/>
+
 The HTTP source creates a generic event ingestion endpoint that you can use to stream events from your service, or a third-party platform into Knock. The events you stream into the HTTP source can then be used to trigger Knock notification workflows.
 
 Knock can receive any structured event data via the HTTP source, as long as you can format JSON and make an HTTP request from the service that produces or consumes events.
@@ -27,7 +47,9 @@ Content-Type: application/json
 
 **Please note**: you'll need to send a single event at a time. There's currently no batch event ingestion endpoint.
 
-## Event schema
+## Legacy event schema
+
+The HTTP source uses a Segment-compatible track event format. This schema is still supported for existing integrations. For new integrations, consider using [incoming webhooks](/integrations/sources/incoming-webhooks/overview) which accept any webhook payload format.
 
 Your events must be structured as JSON with the following schema:
 

diff --git a/content/integrations/sources/incoming-webhooks/clerk.mdx b/content/integrations/sources/incoming-webhooks/clerk.mdx
@@ -0,0 +1,57 @@
+---
+title: How to connect Clerk to Knock
+description: Learn how to use Clerk webhooks to trigger notifications and manage users in Knock.
+section: Integrations > Sources
+layout: integrations
+---
+
+The Clerk source enables you to receive [Clerk webhook events](https://clerk.com/docs/webhooks/overview) in Knock and map them to actions like triggering [workflows](/concepts/workflows), identifying [users](/concepts/users), and managing [tenants](/concepts/tenants). Knock provides a pre-built integration with webhook verification and event-to-action mappings ready to use.
+
+## Prerequisites
+
+- A [Clerk account](https://dashboard.clerk.com) with access to the Webhooks settings
+- A Knock account with at least one workflow configured
+
+## Getting started
+
+<Steps>
+  <Step title="Create the source in Knock">
+    Navigate to **Integrations** > **Sources** in your Knock dashboard and click "Create source." Select **Clerk** from the list of pre-built integrations.
+  </Step>
+  <Step title="Copy the webhook URL">
+    Copy the webhook URL for the Knock environment you want to configure.
+  </Step>
+  <Step title="Add the webhook endpoint in Clerk">
+    In your [Clerk Dashboard](https://dashboard.clerk.com), go to **Webhooks** and click "Add Endpoint." Paste the Knock webhook URL and select the event types you want to subscribe to.
+  </Step>
+  <Step title="Copy the signing secret">
+    After creating the endpoint in Clerk, copy the **Signing Secret** from the endpoint details page.
+  </Step>
+  <Step title="Paste the signing secret in Knock">
+    Back in the Knock dashboard, paste the Clerk signing secret into the source configuration. Knock uses this to verify that incoming webhooks are from Clerk.
+  </Step>
+  <Step title="Review event mappings">
+    Review the pre-configured event-to-action mappings and enable the ones relevant to your use case.
+  </Step>
+</Steps>
+
+## Pre-configured events
+
+The Clerk source comes with mappings for common Clerk webhook event types. You can enable or disable each mapping independently.
+
+| Clerk event | Suggested action | Description |
+| --- | --- | --- |
+| `user.created` | Identify user | Creates a user in Knock when a new user signs up via Clerk |
+| `user.updated` | Identify user | Updates user properties in Knock when profile details change |
+| `user.deleted` | Trigger workflow | Notifies relevant parties when a user account is deleted |
+| `session.created` | Trigger workflow | Triggers a workflow when a user starts a new session |
+| `organization.created` | Set tenant | Creates a tenant in Knock when a new Clerk organization is created |
+| `organization.updated` | Set tenant | Updates tenant properties in Knock when organization details change |
+| `organizationMembership.created` | Subscribe user | Subscribes a user to a tenant when they join an organization |
+| `organizationMembership.deleted` | Unsubscribe user | Unsubscribes a user from a tenant when they leave an organization |
+
+## Customization
+
+You can modify any of the pre-configured mappings or create new ones for additional Clerk event types. When customizing field mappings, use dot notation to reference nested fields in the Clerk webhook payload (e.g. `data.email_addresses[0].email_address`).
+
+For details on building custom event-action mappings and field mapping, see the [custom webhooks documentation](/integrations/sources/incoming-webhooks/custom-webhooks).
diff --git a/content/integrations/sources/incoming-webhooks/custom-webhooks.mdx b/content/integrations/sources/incoming-webhooks/custom-webhooks.mdx
@@ -0,0 +1,135 @@
+---
+title: Custom webhooks
+description: Learn how to connect any service to Knock using custom incoming webhooks with your own verification, event types, and action mappings.
+section: Integrations > Sources
+layout: integrations
+---
+
+Custom webhooks enable you to connect any service that supports webhook delivery to Knock, including internal tools, custom applications, and third-party services without a [pre-built integration](/integrations/sources/incoming-webhooks/overview#pre-built-integrations).
+
+With custom webhooks, you configure the webhook verification scheme, define your event types, and build your own event-to-action mappings with field mapping.
+
+## When to use custom webhooks
+
+- **Connecting services without pre-built integrations.** If Knock doesn't offer a pre-configured integration for your service, you can create your own with custom event-action mappings.
+- **Handling custom events.** Your application might produce events specific to your business logic that need to trigger notifications.
+- **Building internal integrations.** Connect your own services to Knock for centralized notification management.
+
+## Getting started
+
+### Creating a custom webhook source
+
+<Steps>
+  <Step title="Create the source">
+    Navigate to **Integrations** > **Sources** in your Knock dashboard and click "Create source." Select "Custom webhook" from the list.
+  </Step>
+  <Step title="Copy the webhook URL">
+    You'll see a unique webhook URL for each of your Knock [environments](/concepts/environments). Copy the webhook URL for the environment you want to configure and add it as a webhook destination in your service.
+  </Step>
+  <Step title="Configure webhook verification">
+    Configure your webhook verification scheme within Knock. Knock verifies all incoming webhooks using this scheme to confirm they're sent from your service and not a bad actor.
+  </Step>
+</Steps>
+
+### Configuring event types
+
+For custom webhooks, you need to tell Knock how to identify the event type from each incoming payload. You do this by specifying a **key path** that points to the field in the webhook payload that contains the event type name.
+
+For example, if your webhook payloads look like this:
+
+```json
+{
+  "event_name": "task.completed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": { ... }
+}
+```
+
+You would set the key path to `event_name` so Knock can distinguish between different event types like `task.completed`, `task.created`, and so on.
+
+You can also optionally configure a timestamp path to tell Knock which field contains the event timestamp.
+
+### Setting up event-action mappings
+
+After your service starts sending webhooks to Knock, incoming events appear in the source's logs tab.
+
+<Steps>
+  <Step title="Navigate to your source">
+    Go to **Integrations** > **Sources** in your Knock dashboard and select your custom webhook source.
+  </Step>
+  <Step title="Select an event">
+    From the list of received events, click on the event type you want to configure.
+  </Step>
+  <Step title="Create an action mapping">
+    Click "Create action mapping" and select the action you want this event to trigger. A single event can trigger one or many actions in Knock. See [available actions](/integrations/sources/incoming-webhooks/overview#available-actions) for the full list.
+  </Step>
+  <Step title="Map fields">
+    Use the mapping interface to connect fields from your webhook payload to the parameters required by the selected action.
+  </Step>
+  <Step title="Test and activate">
+    Send a test webhook to verify your mapping works correctly, then activate the mapping.
+  </Step>
+</Steps>
+
+## Field mapping
+
+When you configure an action mapping for a webhook event, you specify how fields from the incoming webhook payload map to the parameters your selected action requires.
+
+### How field mapping works
+
+The mapping interface displays your webhook payload structure on one side and the required action parameters on the other.
+
+- **Use dot notation.** Reference nested fields using dot notation like `user.email` or `data.attributes.name`.
+- **Map to multiple parameters.** The same webhook field can populate multiple action parameters.
+
+The interface validates your mappings and shows any required fields that haven't been configured.
+
+### Example: custom application webhook
+
+Here's a webhook payload from a custom task management application:
+
+```json
+{
+  "event_name": "task.completed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "user": {
+    "id": "user_123",
+    "email": "user@example.com",
+    "name": "Jane Smith"
+  },
+  "task": {
+    "id": "task_456",
+    "title": "Review pull request",
+    "project_id": "proj_789"
+  }
+}
+```
+
+The key path configuration for this custom webhook source establishes `event_name` as the key to use to determine which unique event type an event belongs to.
+
+To trigger a workflow when this event occurs:
+
+1. Map the event type `task.completed` to the "Trigger workflow" action.
+2. Select your notification workflow.
+3. Map `user.id` to the workflow's recipients parameter.
+4. Map additional fields like `task.title` to workflow data parameters.
+
+## Viewing logs and debugging
+
+### Event logs
+
+Every webhook received by Knock is logged, regardless of whether it triggered an action.
+
+1. Navigate to **Integrations** > **Sources** in your Knock dashboard.
+2. Select your source.
+3. Click the "Logs" tab.
+
+Event logs show the raw webhook payload, the timestamp it was received, and any actions that were triggered.
+
+### Debugging failed mappings
+
+If a webhook doesn't trigger the expected action, check the event log for error messages. Common issues include:
+
+- **Missing required fields.** The webhook payload doesn't include a field you mapped as a required parameter.
+- **Invalid field paths.** The dot notation path you specified doesn't match the webhook payload structure.
+- **Type mismatches.** The webhook field value doesn't match the expected type for the action parameter.