Segment integration

Integrating KnoCommerce with Segment via webhooks allows you to stream survey events into Segment in real-time.

This guide will walk you through configuring a webhook from KnoCommerce to Segment and using a Segment Function to add a missing event name to the incoming data. Following the steps below will ensure your events arrive in Segment with the proper format.

Overview
Prerequisites
Creating a Segment Function
Configuring Webhooks in KnoCommerce
Validating the Data Flow
Handling Data in Segment
Troubleshooting

Overview

KnoCommerce provides webhooks – HTTP POST callbacks that send event data (like survey response events) to a URL you specify whenever those events occur. By integrating these webhooks with Segment, you can route KnoCommerce data into Segment’s Customer Data Platform and onward to any downstream tools (analytics, CRM, data warehouse, etc.).

Important Note

Segment’s Track API requires an event name for each event. If the event name is missing, Segment might not recognize or forward the data properly. To solve this, we use a Segment Function (custom JavaScript in Segment) to intercept the webhook and insert a default event name when it's not provided. This ensures every incoming webhook is converted into a valid Segment track event with a name.

Prerequisites

Before you begin, make sure you have the following:

Segment account with access to create Sources and Functions. You should be a Workspace Owner or have Source admin permissions to add custom sources.
KnoCommerce account on a Pro plan or above.

Creating a Segment Function

To ensure each incoming event has an event name, we’ll create a Segment Source Function. This function will act as a custom webhook handler: it will receive the JSON from KnoCommerce, add a default event name if needed, and forward it into Segment as a properly formed event. We’ll use Segment’s Functions feature for this.

Let's create the Source Function in Segment:

Open Segment Functions: In the Segment web app, go to the Catalog and select the Functions tab (sometimes called "Functions (Beta)" or similar in the Connections section). Click “New Function”
Choose Function type: When prompted, select “Source” as the function type (since we are creating a source that will ingest data) and click “Build”. A code editor will open where you can define the function’s behavior.
Write the function code: Replace the template code with the custom code below to handle the webhook.
Configure and create the function: Once your code is written, click Configure (usually a button in the top-right of the editor). Give your function a name (e.g., “KnoCommerce Webhook Function”) and optionally a description. Then click “Create Function” to save and deploy it. Segment will build the function – after a brief moment, it should appear in your Functions list.
Connect (deploy) the Function as a Source: After creation, you need to enable this function as an active source in your workspace. On the Functions page, find your new function and click “Connect Source” (this attaches the function to a source slot in your workspace). Follow any prompts (choose the workspace and source name if needed – you may reuse the same name). Once connected, the function is live and has a Webhook URL endpoint.
Retrieve the Function’s webhook URL: In the connected function’s settings, find the Endpoint URL (in the Overview tab or under Settings -> Endpoint). This URL is the address to which KnoCommerce should send its webhooks. Copy the URL – it will look something like https://fn.segmentapis.com/v1/... (Segment generates a unique URL for your function). We'll need this for later.

Custom Code (See Step 3)

/**
 * onRequest is called whenever the webhook sends data to this Function's URL.
 */
async function onRequest(request, settings) {
  const data = request.json();            // Parse incoming JSON payload
  
  // Determine an event name. If the payload has no explicit name, use a default.
  const eventName = data.event || data.type || "KnoCommerce Webhook Event";
  
  // Determine a user identifier for the event
  // Use an ID or email from the payload if available (KnoCommerce may provide a customer id, email, etc.)
  const userId = data.customerId || data.userId || data.email || data.id || null;
  
  // Send the event into Segment
  Segment.track({
    event: eventName,              // Use the derived or default event name
    userId: userId || undefined,   // userId is optional but recommended; undefined if not available
    anonymousId: userId ? undefined : "knocommerce-anon",  // if no userId, use an anonymousId
    properties: data               // attach the entire payload as event properties
  });
}

What does this code do?

Parse the JSON body (request.json()).
Set eventName to an existing field if present (for example, maybe data.event or data.type), otherwise fall back to a default like "KnoCommerce Webhook Event". This ensures we always have an event name for Segment. (Using a descriptive name like “KnoCommerce Survey Response” could be even better, depending on the context of the data.)
Determine userId from the payload. KnoCommerce might provide a customer identifier (e.g., an ID or email). If available, use it as Segment’s userId for proper user tracking. If not, we allow an anonymousId so the event is still accepted by Segment.
Call Segment.track() to forward the event into Segment, with the name, userId/anonymousId, and all original data as properties. This is how we emit a valid Segment event from the function. (Segment’s API expects an event name string and at least one of userId/anonymousId to consider it a well-formed track call).

Configuring Webhooks in KnoCommerce

Now configure KnoCommerce to send its webhook data to your Segment Function.

In this step, you’ll provide the Segment endpoint (from the source above or the function we create later) to KnoCommerce and specify which events to send.

Grab your API credentials: Log into KnoCommerce. Head to Settings > API Access. Click the plus sign to add a new API entry.
1. For Name, use "Segment Integration"
2. For URL, use https://www.segment.com/
3. For Permissions, select all options
4. Once saved, click the pencil icon to access your Client ID and Client Secret
Authenticate with Kno's REST API: Use our Oauth 2.0 instructions to authenticate and grab your token.
Create your webhook: Using the API, create your webhook.
1. For Topic, use response/create
2. For URL, use the Segment Function’s webhook URL from above
Save the webhook: Finalize or save the webhook configuration. You should receive a 201 Created notification.

Validating the Data Flow

With everything set up, it’s important to test and verify that the data is flowing correctly from KnoCommerce to Segment, and that the event name is being added.

Trigger a test event from KnoCommerce: Perform an action that should trigger the webhook, such as responding to one of your live surveys.
Check Segment’s Source Debugger: In Segment, navigate to your Source Function. Go to the Debugger tab for that source. You should see the incoming event appear in real-time (it may be labeled as a Track call). Verify the following in the event data:
- The event name is present and set to the default you specified (e.g., “KnoCommerce Webhook Event” or another name derived in your code). This confirms our function is adding the name.
- The properties of the event contain the payload data from KnoCommerce (all the fields that were in the webhook JSON should be under properties).
- A userId or anonymousId is present. If you used a user identifier from the payload, you should see that as userId on the event.

When everything is working, any time a KnoCommerce event occurs, you should see it in Segment within a few seconds. The event will include the name we added in the Segment Function.

Handling Data in Segment

Once the data is in Segment, you can leverage it like any other Segment event:

Raw data as event properties: The payload from KnoCommerce is now encapsulated in the properties of a Segment track event. This means all the details (survey answers, attribution info, etc.) are available for use in downstream tools. You can view the full JSON in the Segment debugger or in any destination that records event properties (for instance, a data warehouse will have all these fields).
Event naming: The default name you added (or derived) will label the event in Segment. You can use this event name to filter or trigger workflows in other tools. For example, you might have an analytics tool listen for “KnoCommerce Webhook Event” occurrences, or you might decide to map it to a more descriptive name in the function (e.g., “Survey Submitted” if all events are survey submissions). Make sure the name is meaningful for your downstream applications or consider using different event names if you handle multiple event types (you can incorporate logic in the function to set different names based on payload content).
Routing to destinations: With the Segment source capturing these events, you can now connect any number of Destinations to this source (if not already). Segment will fan-out the data to those destinations in real-time. For example, you could send the events to a marketing automation platform, to Slack via a webhook (using Segment’s Webhook destination), or simply store them in your data warehouse. Once in Segment, the data can be sent to any tool for which you’ve configured a destination – Segment acts as a hub routing the data outward. To do this, go to the Destinations tab in Segment and add whichever integrations you need, associating them with your KnoCommerce source.
Further processing: You can also transform or filter the data within Segment. For instance, you might use Segment’s Transformations (if available on your plan) to rename properties or drop unwanted fields before the data reaches certain destinations. But these are optional.

In summary, the raw webhook data is now a normalized Segment event. You’ve effectively connected an otherwise unsupported source (KnoCommerce) to Segment using a custom function. From Segment’s perspective, it’s just another incoming event stream that can be “sent to other destinations and acted on” across your stack.

Troubleshooting

If you encounter issues, here are common problems and how to resolve them:

No data arriving in Segment: If you don’t see any events in Segment’s debugger, double-check the webhook setup:
- Ensure the webhook URL in KnoCommerce exactly matches the Segment Function endpoint. Any typos or missing parts will prevent delivery.
- Verify that the webhook is active on KnoCommerce and firing. You can list your webhooks to confirm.
Function not triggering or errors: If you’re using the Segment Function and no event shows up, go to the function in Segment’s UI and look for an error log or invocation log. There might be a coding error. For example, a syntax error or calling Segment.track incorrectly could cause the function to fail silently. Edit the function code if needed and redeploy. Adding some console.log() statements in the code (and checking logs) can help debug what data is coming in and how your function handles it.
Event shows in Segment but missing event name: This means the function ran but didn’t set the name as expected. Double-check how you’re determining eventName in code. The payload may not have the field you assumed. For instance, if data.event was undefined, maybe the relevant info is in data.type or another field provided by KnoCommerce. Adjust the code to use the correct field or a default. (If absolutely no identifier for event type is present in the payload, you will have to rely on a static default name as we did.) After changes, deploy the function again and test.
Multiple or duplicate events: If you accidentally left the KnoCommerce webhook pointing to the old Segment HTTP endpoint and also set up the new function, you might ingest the data twice (once directly, once via the function). To fix this, use only one integration path. We recommend using the Segment Function exclusively (for simplicity). Remove or disable any duplicate webhook configurations. Ensure KnoCommerce is only sending to the intended endpoint.
General debugging: Use Segment’s Source Debugger as a primary tool to confirm incoming calls. It shows each API call reaching Segment. If an event is malformed, it might show up in the debugger with an error or not at all. Using the debugger in tandem with console logs in the function can pinpoint where things might be failing.

Finally, if data still does not appear as expected, you may reach out to Segment support or check their documentation for Source Functions.