Events API v1.0 Technical Overview

Overview

The Knotch Events API lets you send server-side conversion events from CRMs, data warehouses, or analytics tools directly into Knotch. These events can then be measured, filtered, and attributed alongside Site Events (Conversions, Actions) in Knotch One — connecting your offline outcomes (like Closed Won, SQL, or Renewal) to your digital content performance.

These events will appear as ‘API Conversions’ throughout Knotch One — including Event Builder, Dashboards, Leaderboards, Funnels, Quadrants, and more — and can be found in all the places where Site Conversions (standard Knotch Conversions) are displayed.

You can use this API to:

• Send conversion or engagement events from your CRM, marketing automation, or analytics tools

• Validate event payloads in simulation mode before sending live data

• Track API-based conversions alongside native Knotch events

• Attribute API Conversions to site content, performance metrics, and visitor journeys

Authentication

All requests must be sent over HTTPS and include your Knotch API key.

Authorization: Bearer <api-key>

To obtain or rotate an API key, contact your Knotch Client Success Manager.

Endpoints

1. Direct API Endpoint
Use this endpoint to POST events directly from your server or automation platform.

POST https://events.knotch.it/conversion_events/<account_id>?simulate=false
Content-Type: application/json
Authorization: Bearer <api-key>

2. Segment Webhook Endpoint
The Knotch Events API also supports Segment Webhooks — allowing clients to stream data directly from Segment to Knotch with no SDK changes.

POST https://events.knotch.it/conversion_events/segment/<account_id>

Segment setup steps:

1. Go to Connections → Catalog → Destinations → Webhooks (Actions).

2. Configure the Webhook or Destination Function to point to your Knotch endpoint.

3. Add an Authorization header (Bearer <api-key>).

4. Map your fields to match the payload schema below.

Payload Schema

Each request includes an "events" array (up to 100 events per batch).

{
  "events": [
    {
      "event": {
        "event_name": "ClosedWon",
        "timestamp": 1720727400,
        "event_id": "OPP-12345"
      },
      "identity": {
        "kn_cs_visitor_id": "KVID-abc123",
        "gclid": {
          "value": "CjwK...",
          "first_seen": 1724800000,
          "last_seen": 1724886400
        },
        "ecid": "ECID-xyz-123",
        "ga_client_id": "GA1.2.111.222",
        "marketo_lead_id": "MKT-445566"
      },
      "value": {
        "value": 50000.00,
      },
      "event_source": ["Salesforce"],
      "test_event_code": "TEST123"
    }
  ]
}

Field Definitions & Requirements

Response Codes

Deduplication & Validation

• Maximum 100 events per request
• Deduplication is performed by event_id (and identity when available)
• Duplicate events return HTTP 409 Conflict
• Validation ensures at least one identity (e.g., Knotch ID or external ID)

Segment Authentication & Security

• Add an Authorization header to your Segment webhook:
Authorization: Bearer <api-key>
• Each Webhook Action includes an X-Signature HMAC (Segment signs the first event in each batch). Knotch validates this for security.
• Segment retries failed posts with exponential backoff.
• Deduplication uses messageId when present.

Example cURL (Direct POST)

curl -X POST 'https://events.knotch.it/conversion_events/56045b70-62ec-9c4e-0a2b-744300000000?simulate=false' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [{
      "event": { "event_name": "ClosedWon", "timestamp": 1720727400, "event_id": "OPP-12345" },
      "identity": { "kn_cs_visitor_id": "KVID-abc123" },
      "value": { "value": 50000 }
    }]
  }'

Testing & QA

You can safely test your integration by setting:

simulate=true

This validates structure, required fields, and authentication without storing any data.
You’ll receive 200 OK with the message:

{"message": "Events validated successfully"}

What You’ll See in Knotch Once

Once your API Conversion Events are successfully received, you’ll see them appear across Knotch One similar to Site Conversions.

Where they appear:

• Conversions Leaderboard - listed as API Conversion events alongside your Site Conversions, complete with attributed content metrics (metrics refresh every 24 hours)

• Conversions Dashboard – in the Conversions live data filter as API Conversions

• Pages and Tags Leaderboards – in the Conversions live data filter as API Conversions

• Quadrants – in the Conversions live data filter as API Conversions

• Funnels – in Funnel Builder, when adding Conversions to your step conditions, you can select Site or API Conversions

Tip: If your event doesn’t immediately appear, confirm that the event name matches your saved Event definition and that Knotch Visitor ID was properly included in your event payload.