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
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.
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:
Go to Connections → Catalog → Destinations → Webhooks (Actions).
Configure the Webhook or Destination Function to point to your Knotch endpoint.
Add an Authorization header (Bearer <api-key>).
Map your fields to match the payload schema below.
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 | Type | Required | Description |
| List |
| List of events. Can have maximum of 100 unique events. Requires at least 1 event. |
| Object |
| Event-level object |
| String |
| Name of the event (e.g., |
| Integer |
| UTC Unix timestamp (e.g., |
| String |
| Unique identifier for the event |
| Object |
| Identity object used for ID resolution and key value pairing |
| String |
| Knotch Visitor ID |
| String | – | Google Click ID |
| String | – | Google Analytics client ID |
| String | – | Marketo Lead ID |
| Object | - | Value object used for passing in value or revenue data for offline events |
| Float | – | Revenue or numeric value associated with the event |
| Array | – | Source of the event (e.g., Salesforce, Marketo) |
Code | Summary | Description |
200 | OK | Everything worked as expected |
400 | Bad Request | Failed due to unknown errors |
403 | Unauthorized | The API key doesn’t have permissions to perform the request |
422 | Invalid payload | The request was unacceptable, often due to missing a required parameter |
500, 502, 503, 504 | Server Errors | Something went wrong on Knotch’s end |
• 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)
• 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.
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 }
}]
}'You can safely test your integration by setting:
simulate=trueThis validates structure, required fields, and authentication without storing any data.
You’ll receive 200 OK with the message:
{"message": "Events validated successfully"}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.