feat: add incoming webhook docs

content/integrations/sources/clerk.mdx

@@ -0,0 +1,66 @@
+---
+title: Clerk source
+description: Receive Clerk webhook events in Knock to trigger workflows and automate actions based on authentication and user management events.
+section: Integrations > Sources
+layout: integrations
+---
+
+The Clerk source enables you to receive [Clerk webhook events](https://clerk.com/docs/webhooks/overview) directly in Knock. Clerk sends webhook callbacks when events occur in your application, such as a new user signing up, a session being created, or an organization being updated. Knock verifies each payload using your Clerk webhook signing secret, identifies the event type, and executes the actions you configure.
+
+This integration is useful for building notifications around user lifecycle events: triggering welcome workflows when users sign up, notifying admins about organization changes, or syncing user data into Knock when profile details are updated.
+
+## Prerequisites
+
+- A Knock account with at least one [environment](/concepts/environments) configured.
+- A Clerk application with access to the [Webhooks settings](https://dashboard.clerk.com) in the Clerk dashboard.
+
+## Getting started
+
+<Steps>
+  <Step title="Create the source in Knock">
+    Navigate to **Integrations** > **Sources** in the Knock dashboard. Click "Create source" and select **Clerk** as the source type. Give it a name and description.
+  </Step>
+  <Step title="Copy the webhook URL">
+    After creating the source, copy the webhook URL for the environment you want to configure.
+  </Step>
+  <Step title="Add the webhook endpoint in Clerk">
+    In the [Clerk dashboard](https://dashboard.clerk.com), navigate to **Webhooks** and click "Add endpoint." Paste the Knock webhook URL and select the events you want Clerk to send.
+  </Step>
+  <Step title="Copy the signing secret into Knock">
+    After creating the endpoint in Clerk, Clerk provides a signing secret. Copy this value and paste it into the **Signing secret** field in your Knock source environment configuration.
+  </Step>
+</Steps>
+
+Once configured, Clerk sends webhook events to Knock in real time. You can verify that events are arriving by checking the event logs on the source environment page.
+
+## Pre-configured events
+
+Clerk sends events for user, session, and organization lifecycle changes. Below are common events you might map to actions in Knock. You can enable or disable individual event types from the source environment configuration.
+
+| Event type | Description |
+| --- | --- |
+| `user.created` | A new user signed up |
+| `user.updated` | User profile details were updated |
+| `user.deleted` | A user was deleted |
+| `session.created` | A new session was created (user signed in) |
+| `session.ended` | A session ended (user signed out) |
+| `organization.created` | A new organization was created |
+| `organization.updated` | Organization details were updated |
+| `organizationMembership.created` | A user was added to an organization |
+| `organizationMembership.deleted` | A user was removed from an organization |
+
+See the [Clerk webhook events documentation](https://clerk.com/docs/webhooks/sync-data) for the full list of available events.
+
+## Customization
+
+You can modify the default action mappings or add new ones for any event type Knock receives from Clerk. For details on how field mapping works with dot-notation paths, see the [HTTP source](/integrations/sources/http) page.
+
+If you need to map Clerk events to actions beyond triggering workflows, see the full list of [available actions](/integrations/sources/overview#available-actions) in the sources overview.
+
+## Event idempotency
+
+Knock automatically configures idempotency for the Clerk source so duplicate events are not processed twice. By default, Knock uses `[IDEMPOTENCY_KEY_PATH]` from the Clerk webhook payload as the idempotency key.
+
+You can change the idempotency key field or disable idempotency checks from the **Settings** tab in your source environment configuration. Events without an idempotency key attribute are processed normally.
+
+For details on how Knock handles idempotent events, key validation rules, and the default 24-hour idempotency window, see the [source event idempotency](/integrations/sources/overview#source-event-idempotency) section of the sources overview.

content/integrations/sources/posthog.mdx

@@ -0,0 +1,60 @@
+---
+title: PostHog source
+description: Receive PostHog webhook events in Knock to trigger workflows and automate actions based on product analytics events.
+section: Integrations > Sources
+layout: integrations
+---
+
+The PostHog source enables you to receive [PostHog webhook events](https://posthog.com/docs/webhooks) directly in Knock. PostHog sends webhook callbacks when actions fire in your product analytics, such as a user completing a key funnel step, a feature flag change, or a custom event you define. Knock verifies each payload, identifies the event type, and executes the actions you configure.
+
+This integration is useful for building notifications triggered by product behavior: reaching out to users who complete onboarding milestones, alerting your team when a feature flag is changed, or triggering re-engagement workflows based on usage patterns.
+
+## Prerequisites
+
+- A Knock account with at least one [environment](/concepts/environments) configured.
+- A PostHog project with access to the [Webhooks settings](https://posthog.com/docs/webhooks) in the PostHog app.
+
+## Getting started
+
+<Steps>
+  <Step title="Create the source in Knock">
+    Navigate to **Integrations** > **Sources** in the Knock dashboard. Click "Create source" and select **PostHog** as the source type. Give it a name and description.
+  </Step>
+  <Step title="Copy the webhook URL">
+    After creating the source, copy the webhook URL for the environment you want to configure.
+  </Step>
+  <Step title="Configure a webhook destination in PostHog">
+    In PostHog, navigate to the **Data pipelines** section and add a new webhook destination. Paste the Knock webhook URL. You can configure which actions or events trigger the webhook.
+  </Step>
+  <Step title="Test the connection">
+    Trigger a test action in PostHog and verify that the event appears in the Knock source event logs.
+  </Step>
+</Steps>
+
+Once configured, PostHog sends webhook events to Knock when the specified actions or events fire. You can verify that events are arriving by checking the event logs on the source environment page.
+
+## Pre-configured events
+
+PostHog webhook events are driven by the actions and events you configure in your PostHog project. Common scenarios include:
+
+| Event type | Description |
+| --- | --- |
+| Action webhooks | Fired when a PostHog action matches (for example, a user clicks a specific button or views a key page) |
+| Custom events | Fired when your application sends a custom event to PostHog that matches your webhook criteria |
+| Feature flag changes | Fired when a feature flag is updated |
+
+The exact event types depend on how you configure your PostHog actions and webhook destinations. See the [PostHog webhooks documentation](https://posthog.com/docs/webhooks) for more details on available triggers and payload formats.
+
+## Customization
+
+You can modify the default action mappings or add new ones for any event type Knock receives from PostHog. For details on how field mapping works with dot-notation paths, see the [HTTP source](/integrations/sources/http) page.
+
+If you need to map PostHog events to actions beyond triggering workflows, see the full list of [available actions](/integrations/sources/overview#available-actions) in the sources overview.
+
+## Event idempotency
+
+Knock automatically configures idempotency for the PostHog source so duplicate events are not processed twice. By default, Knock uses `[IDEMPOTENCY_KEY_PATH]` from the PostHog webhook payload as the idempotency key.
+
+You can change the idempotency key field or disable idempotency checks from the **Settings** tab in your source environment configuration. Events without an idempotency key attribute are processed normally.
+
+For details on how Knock handles idempotent events, key validation rules, and the default 24-hour idempotency window, see the [source event idempotency](/integrations/sources/overview#source-event-idempotency) section of the sources overview.

content/integrations/sources/rudderstack.mdx

@@ -58,10 +58,20 @@ Once your RudderStack destination is set up all events you trigger from the Rudd
 
 From the source environment configuration page click the "View in environment" button on one of the source environments. You'll be taken to the RudderStack source in the environment you selected and you should see events sent. If you don't, try clicking the refresh button on the top of the list to refetch any incoming events.
 
+### How Knock translates RudderStack events
+
+Although RudderStack has its own event format, Knock translates incoming events 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. For a RudderStack `track` call with associated `properties`, Knock uses those `properties` to set the `data` field.
+- `event`. The original event, as originally received by Knock.
+
 ## Triggering workflows from received events
 
 You can add a **track event** as a trigger to your workflow directly from the workflow builder. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you'll be able to select the event and map its properties into the data the workflow needs.
 
+You can have any number of workflows triggered by each event. If no workflow is configured for an event, the event is logged but no action is taken.
+
 <Callout
   emoji="✨"
   title="Using properties."
@@ -83,15 +93,30 @@ You can add a **track event** as a trigger to your workflow directly from the wo
   }
 />
 
-[Read more on configuring workflow triggers](/integrations/sources/overview#workflow-triggers)
+<Callout
+  type="alert"
+  title="For workflow triggers, no more than 1000 recipients can be included in
+        each event."
+  text={
+    <>
+      If you exceed this limit, Knock will not process your workflow trigger and
+      instead generate an error log. <br />
+      <br />
+      If you need to manage a large list of recipients you might want to
+      consider using our{" "}
+      <a href="/concepts/subscriptions">subscriptions feature</a> to have Knock
+      manage the set of recipients who need to be notified instead.
+    </>
+  }
+/>
 
 ## Disabling a trigger
 
 Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, you can go to the trigger page and toggle its status to "Inactive." Keep in mind that this will disable that trigger for the current environment only. When you're ready to trigger the workflow again, you can set it back to "Active."
 
 ## Enabling Identify Events
 
-When RudderStack sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `userId` as the user's `id`, as well as `name`, `email`, `phone` (mapped as `phone_number` in Knock), `avatar`, `locale`, `timezone`, and any additional custom properties provided in the `traits` object.
+When RudderStack sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `userId` as the user's `id`, as well as `name`, `email`, `phone` (mapped as `phone_number` in Knock), `avatar`, `locale`, `timezone`, and any additional custom properties provided in the `traits` object. All custom properties are stored on the Knock user object and can be used in templates and other parts of Knock that rely on user properties.
 
 <Callout
   emoji="⚠️"
@@ -135,6 +160,24 @@ To enable handling of identify events, open the settings for the source in the r
   alt="A screenshot of how to toggle Knock handling RudderStack identify calls"
 />
 
+<Callout
+  type="alert"
+  title="Remember:"
+  text={
+    <>
+      if you send Knock an event that includes a recipient not yet identified in
+      Knock, our system will not generate a workflow run for that user. <br />
+      <br />
+      For use cases such as new signup events, where events often reach Knock
+      before identify calls, consider{" "}
+      <a href="#inline-identify-users-in-a-rudderstack-event">
+        inline identification
+      </a>{" "}
+      of users in your RudderStack events.
+    </>
+  }
+/>
+
 ## Inline identify users in a RudderStack event
 
 <Callout
@@ -196,6 +239,36 @@ To ensure that the user is notified, we'd change the id reference in `recipients
 
 You can learn more about inline identification in [our documentation on identifying recipients](/managing-recipients/identifying-recipients).
 
+## Event idempotency
+
+You can enable idempotency checks to deduplicate RudderStack events that have already been received and processed. This is useful if you know RudderStack may send duplicate events to Knock.
+
+Knock automatically uses the `messageId` field from the RudderStack track spec as the idempotency key. No additional field configuration is needed — RudderStack includes a `messageId` in every track and identify event by default.
+
+To enable idempotency, open the **Settings** tab for your source environment configuration and toggle idempotency checks on.
+
+<Image
+  src="/images/integrations/sources/source-event-idempotency.png"
+  alt="A screenshot of where to configure idempotency for your Source."
+  width={800}
+  height={400}
+  className="rounded-md mx-auto border border-gray-200"
+/>
+
+```json title="An example RudderStack event with a valid idempotency key."
+{
+  "type": "track",
+  "event": "user.created",
+  "messageId": "some-id-from-rudderstack",
+  "properties": {
+    "id": "user-1",
+    "email": "user-1@example.com"
+  }
+}
+```
+
+Events without a `messageId` are processed normally. For details on how Knock handles idempotent events, key validation rules, and the default 24-hour idempotency window, see the [source event idempotency](/integrations/sources/overview#source-event-idempotency) section of the sources overview.
+
 ## Video walkthrough
 
 This video is Segment-specific, but you can apply any of the portions within the Knock dashboard to RudderStack as well.

content/integrations/sources/segment.mdx

@@ -73,10 +73,20 @@ Once your Segment destination is set up, all events you trigger from the Segment
 
 From the source environment configuration page, click the "View in environment" button on one of the source environments. You'll be taken to the Segment source in the environment you selected, and you should see events sent. If you don't, try clicking the refresh button at the top of the list to refetch any incoming events.
 
+### How Knock translates Segment events
+
+Although Segment has its own event format, Knock translates incoming events 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. For a Segment `track` call with associated `properties`, Knock uses those `properties` to set the `data` field.
+- `event`. The original event, as originally received by Knock.
+
 ## Triggering workflows from received events
 
 You can add a **track event** as a trigger to your workflow directly from the workflow builder. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you'll be able to select the event and map its properties into the data the workflow needs.
 
+You can have any number of workflows triggered by each event. If no workflow is configured for an event, the event is logged but no action is taken.
+
 <Callout
   emoji="✨"
   title="Using event data in workflow triggers."
@@ -105,15 +115,30 @@ You can add a **track event** as a trigger to your workflow directly from the wo
 }
 />
 
-[Read more on configuring workflow triggers](/integrations/sources/overview#workflow-triggers)
+<Callout
+  type="alert"
+  title="For workflow triggers, no more than 1000 recipients can be included in
+        each event."
+  text={
+    <>
+      If you exceed this limit, Knock will not process your workflow trigger and
+      instead generate an error log. <br />
+      <br />
+      If you need to manage a large list of recipients you might want to
+      consider using our{" "}
+      <a href="/concepts/subscriptions">subscriptions feature</a> to have Knock
+      manage the set of recipients who need to be notified instead.
+    </>
+  }
+/>
 
 ## Disabling a trigger
 
 Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, you can go to the trigger page and toggle its status to "Inactive." Keep in mind that this will disable that trigger for the current environment only. When you're ready to trigger the workflow again, you can set it back to "Active."
 
 ## Enabling Identify events
 
-When Segment sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `userId` as the user's `id`, as well as `name`, `email`, `phone` (mapped as `phone_number` in Knock), `avatar`, `locale`, `timezone`, and any additional custom properties provided in the `traits` object.
+When Segment sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `userId` as the user's `id`, as well as `name`, `email`, `phone` (mapped as `phone_number` in Knock), `avatar`, `locale`, `timezone`, and any additional custom properties provided in the `traits` object. All custom properties are stored on the Knock user object and can be used in templates and other parts of Knock that rely on user properties.
 
 To enable the handling of identify events, open the settings for the source in the relevant Knock environment. You can then enable or disable handling identify events accordingly.
 
@@ -204,6 +229,36 @@ To ensure the user is notified, we'd change the id reference in `recipients` to
 
 You can learn more about inline identification in [our documentation on identifying recipients](/managing-recipients/identifying-recipients).
 
+## Event idempotency
+
+You can enable idempotency checks to deduplicate Segment events that have already been received and processed. This is useful if you know Segment may send duplicate events to Knock.
+
+Knock automatically uses the `messageId` field from the Segment track spec as the idempotency key. No additional field configuration is needed — Segment includes a `messageId` in every track and identify event by default.
+
+To enable idempotency, open the **Settings** tab for your source environment configuration and toggle idempotency checks on.
+
+<Image
+  src="/images/integrations/sources/source-event-idempotency.png"
+  alt="A screenshot of where to configure idempotency for your Source."
+  width={800}
+  height={400}
+  className="rounded-md mx-auto border border-gray-200"
+/>
+
+```json title="An example Segment event with a valid idempotency key."
+{
+  "type": "track",
+  "event": "user.created",
+  "messageId": "some-id-from-segment",
+  "properties": {
+    "id": "user-1",
+    "email": "user-1@example.com"
+  }
+}
+```
+
+Events without a `messageId` are processed normally. For details on how Knock handles idempotent events, key validation rules, and the default 24-hour idempotency window, see the [source event idempotency](/integrations/sources/overview#source-event-idempotency) section of the sources overview.
+
 ## Video walkthrough
 
 <div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>