--- title: "Events API v1.1 Technical Overview" description: "Send server-side or CRM-based conversion events to Knotch" url: https://help.knotch.com/en/articles/159-events-api-v11-technical-overview collection: "Events API" updated: 2026-04-28 language: en --- # Events API v1.1 Technical Overview Send server-side or CRM-based conversion events to Knotch ### **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. ```javascript Authorization: Bearer ``` 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. ```javascript POST https://events.knotch.it/conversion_events/?simulate=false Content-Type: application/json Authorization: Bearer ``` **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. ```javascript POST https://events.knotch.it/conversion_events/segment/ ``` **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 ). 4. Map your fields to match the payload schema below. * * * ### Payload Schema Each request includes an "events" array (up to 100 events per batch). The identity field below is strictly an example; however, the ID string passed in should align with the agreed-upon tracked ID prior to integration. Only a single custom ID is currently supported. ```javascript { "events": [ { "event": { "event_name": "ClosedWon", "timestamp": 1720727400, "event_id": "OPP-12345" }, "identity": { "gclid": { "value": "CjwK...", "first_seen": 1724800000, "last_seen": 1724886400 }, "value": { "value": 50000.00, }, "event_source": ["Salesforce"], "test_event_code": "TEST123" } ] } ``` ### Field Definitions & Requirements

Field	Type	Required	Description
`events`	List	✅	List of events. Can have maximum of 100 unique events. Requires at least 1 event.
`event`	Object	✅	Event-level object
`event_name`	String	✅	Name of the event (e.g., `FormSubmitted`, `ClosedWon`)
`timestamp`	Integer	✅	UTC Unix timestamp (e.g., `1729538400`)
`event_id`	String	✅	Unique identifier for the event
`identity`	Object	✅	Identity object used for ID resolution and key value pairing
`gclid`	String	–	Google Click ID
`value`	Object	-	Value object used for passing in value or revenue data for offline events
`value`	Float	–	Revenue or numeric value associated with the event
`event_source`	Array	–	Source of the event (e.g., Salesforce, Marketo)

* * * ### Response Codes

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

* * * ### 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 ` • 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) ```javascript curl -X POST 'https://events.knotch.it/conversion_events/56045b70-62ec-9c4e-0a2b-744300000000?simulate=false' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "events": [{ "event": { "event_name": "ClosedWon", "timestamp": 1720727400, "event_id": "OPP-12345" }, "identity": { "gclid": "66876767" }, "value": { "value": 50000 } }] }' ``` * * * ### Testing & QA You can safely test your integration by setting: ```javascript simulate=true ``` This validates structure, required fields, and authentication without storing any data. You’ll receive 200 OK with the message: ```javascript {"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 the identity string was properly included in your event payload.