Event reference

What this lets you do

Build against the exact payload of every event type Traceten delivers. All examples on this page are complete, valid deliveries under api_version: "2026-07-01". Every delivery shares the same envelope: id, type, api_version, created, and a type-specific data object. This page documents each type and its data. All wire fields are snake_case. The taxonomy is additive-only. New types may be added; existing types and fields are never removed or renamed. Route on type and ignore values you do not recognize.

`ai_session.classified`

Fires when a session on your site is classified as AI-referred. Exactly one delivery per AI session, deduplicated per session, sent the moment classification completes. This is the default subscription for new endpoints.

{
  "id": "whd_01j9x7v3k8q4r2m5n6p7s8t9u0",
  "type": "ai_session.classified",
  "api_version": "2026-07-01",
  "created": 1752307200000,
  "data": {
    "event_id": "evt_01j9x7v3k1e2f3g4h5i6j7k8l9",
    "site_id": "0b6f3c2a-9d4e-4f1b-8a7c-2d5e6f7a8b9c",
    "session_id": "9f2c4b1d-7e3a-42b5-8c1d-2e5f6a7b8c9d",
    "visitor_id": "123e4567-e89b-42d3-a456-426614174000",
    "url": "https://acme.com/pricing",
    "ai_source": "ChatGPT",
    "ai_confidence": 0.94,
    "detection_method": "rules",
    "country": "US",
    "timestamp": "2026-07-12T08:00:00.000Z"
  }
}

`data` fields

Field	Type	Description
`event_id`	string	Unique id of the classified event, assigned at the edge.
`site_id`	string	Your site key: the `ttid_…` value shown on the install page and used as `data-site`. Not the site UUID from the dashboard URL.
`session_id`	string	Browser-session identifier the classification belongs to.
`visitor_id`	string	Persistent pseudonymous visitor identifier.
`url`	string	Page URL at the time of the event, reduced to origin + path. Query strings and fragments are stripped before delivery.
`ai_source`	string	Canonical AI source name, e.g. `"ChatGPT"`, `"Perplexity"`, `"Claude"`. New sources appear over time; treat as an open set.
`ai_confidence`	number	Classification confidence, `0.0` to `1.0`.
`detection_method`	string	Which detection method produced the classification, for example `"rules"` (or its legacy alias `"rule"`) for rule-based matching.
`country`	string \| null	ISO 3166-1 alpha-2 country code, or `null` when unavailable.
`timestamp`	string	ISO-8601 UTC time of the event.

`conversion.attributed`

Fires when a conversion (a purchase or any custom goal) is attributed to an AI source, immediately after Traceten records the attribution. A conversion with no AI-referred session in its journey never fires this event. Exactly one event per conversion, not one per attribution model: the top-level fields carry the canonical model (last-touch in v1), and models[] carries the full four-model breakdown for the same AI source. Because the breakdown is scoped to the canonical (last-touch) source, a model that credits a different source shows credit_fraction: 0 for it. A money-carrying conversion (Stripe or Shopify purchase). This journey had two AI touches, ChatGPT first and Perplexity last, so first-touch assigns Perplexity nothing:

{
  "id": "whd_01j9x8a4m2n3p4q5r6s7t8u9v0",
  "type": "conversion.attributed",
  "api_version": "2026-07-01",
  "created": 1752307260000,
  "data": {
    "conversion_id": "conv_01j9x8a4m9w8x7y6z5a4b3c2d1",
    "site_id": "0b6f3c2a-9d4e-4f1b-8a7c-2d5e6f7a8b9c",
    "session_id": "9f2c4b1d-7e3a-42b5-8c1d-2e5f6a7b8c9d",
    "ai_source": "Perplexity",
    "event_name": "purchase",
    "attribution_model": "last_touch",
    "credit_fraction": 1,
    "revenue_cents_attributed": 12999,
    "currency": "USD",
    "models": [
      { "model": "first_touch", "credit_fraction": 0, "revenue_cents_attributed": 0 },
      { "model": "last_touch", "credit_fraction": 1, "revenue_cents_attributed": 12999 },
      { "model": "linear", "credit_fraction": 0.5, "revenue_cents_attributed": 6500 },
      { "model": "time_decay", "credit_fraction": 0.6, "revenue_cents_attributed": 7800 }
    ],
    "timestamp": "2026-07-12T08:01:00.000Z"
  }
}

For a non-purchase goal, revenue_cents_attributed and currency are absent at the top level and every models[].revenue_cents_attributed is null. There is no money to split, and Traceten never fabricates a $0. A signup attributed to a single AI touch:

{
  "id": "whd_01j9x8c5n3p4q5r6s7t8u9v0w1",
  "type": "conversion.attributed",
  "api_version": "2026-07-01",
  "created": 1752307320000,
  "data": {
    "conversion_id": "conv_01j9x8c5n1a2b3c4d5e6f7g8h9",
    "site_id": "0b6f3c2a-9d4e-4f1b-8a7c-2d5e6f7a8b9c",
    "session_id": "2d8e6a4c-1b3f-42a5-9c7d-1e2f3a4b5c6d",
    "ai_source": "Claude",
    "event_name": "signup",
    "attribution_model": "last_touch",
    "credit_fraction": 1,
    "models": [
      { "model": "first_touch", "credit_fraction": 1, "revenue_cents_attributed": null },
      { "model": "last_touch", "credit_fraction": 1, "revenue_cents_attributed": null },
      { "model": "linear", "credit_fraction": 1, "revenue_cents_attributed": null },
      { "model": "time_decay", "credit_fraction": 1, "revenue_cents_attributed": null }
    ],
    "timestamp": "2026-07-12T08:02:00.000Z"
  }
}

Note the distinction: 0 means “this model assigned no credit to a real-money conversion”; null means “this conversion carries no money at all”.

`data` fields

Field	Type	Description
`conversion_id`	string	Unique id of the conversion event.
`site_id`	string	Your site key: the `ttid_…` value shown on the install page and used as `data-site`. Not the site UUID from the dashboard URL.
`session_id`	string	Browser-session token credited under the canonical model.
`ai_source`	string	Canonical AI source name for the credited (last-touch) session.
`event_name`	string	The goal name, e.g. `"purchase"`, `"signup"`.
`attribution_model`	string	The canonical model whose credit the top-level fields carry. `"last_touch"` in v1. One of `first_touch`, `last_touch`, `linear`, `time_decay`.
`credit_fraction`	number	Fraction of credit assigned to the AI source under the canonical model, `0.0` to `1.0`.
`revenue_cents_attributed`	integer	Revenue attributed under the canonical model, in integer minor units of `currency` (e.g. `12999` for $129.99). Present only for money-carrying conversions, always together with `currency`.
`currency`	string	Uppercase ISO 4217 code, e.g. `"USD"`. Present only alongside `revenue_cents_attributed`.
`models`	array	Full four-model breakdown; one entry per model, always all four. Each entry reports the credit that model assigns to the canonical `ai_source`.
`models[].model`	string	`first_touch`, `last_touch`, `linear`, or `time_decay`.
`models[].credit_fraction`	number	Credit fraction that model assigns to the canonical `ai_source`, `0.0` to `1.0`. `0` when the model credits a different source.
`models[].revenue_cents_attributed`	integer \| null	Revenue under that model in minor units, or `null` for non-purchase goals.
`timestamp`	string	ISO-8601 UTC time of the conversion.

`webhook.ping`

The test and verification event. Sent in exactly two situations: once automatically when you register an endpoint (to verify it), and whenever you click Send test event on the endpoint detail page. It never fires as part of your site’s traffic. It travels the exact same signing and delivery path as real events, so a successful ping proves the real path works, and its outcome drives the endpoint’s verification status. Unlike real events, a ping gets exactly one attempt. It never enters the retry schedule; if it fails, click Send test event again.

{
  "id": "whd_01j9x6t2j7p3q1l4m5n6o7p8q9",
  "type": "webhook.ping",
  "api_version": "2026-07-01",
  "created": 1752307140000,
  "data": {
    "site_id": "0b6f3c2a-9d4e-4f1b-8a7c-2d5e6f7a8b9c",
    "message": "Traceten webhook test — your endpoint is receiving deliveries."
  }
}

`data` fields

Field	Type	Description
`site_id`	string	UUID of the site the ping was triggered for: the site’s internal id, the one in your dashboard URL.
`message`	string	Human-readable confirmation. Informational only; do not parse it.

site_id means two different things across event types. On ai_session.classified and conversion.attributed, site_id is your site key, the ttid_… value used as data-site in the snippet. On webhook.ping it is the site’s internal UUID from the dashboard URL. The two never equal each other. If your handler keys anything on site_id, branch on event type first, or ignore the ping’s site_id and match on the endpoint instead.

What webhooks never carry

Payloads are stable projections of Traceten’s internal records, not the records themselves. The following fields exist internally but are deliberately excluded from every event, permanently:

Excluded	Why
`ip_hash`	Derived from the visitor’s IP address. Network-level identifiers never leave Traceten.
`user_agent`	High-entropy fingerprinting surface.
`referrer`	Referring URLs can embed personal data (search terms, profile URLs, tokens).
`asn`	Network (autonomous system) data is an indirect location and identity signal.
Emails, names, phone numbers	Traceten does not collect PII on the default path, so there is nothing to send.

Additionally, the url field in ai_session.classified is reduced to origin + path before delivery. Query strings and fragments routinely carry emails, tokens, and session state, so they are stripped and structurally cannot ride along. conversion.attributed carries no visitor_id. That is not a privacy exclusion (visitor_id is pseudonymous and is included in ai_session.classified); the credited session_id is simply sufficient to attribute a conversion. Join the two event types on session_id if you need visitor-level analysis. See what data we collect for the full picture of what Traceten does and does not store.

Webhooks

What this lets you do

`ai_session.classified`

`data` fields

`conversion.attributed`

`data` fields

`webhook.ping`

`data` fields

What webhooks never carry

Next

​What this lets you do

​ai_session.classified

​data fields

​conversion.attributed

​data fields

​webhook.ping

​data fields

​What webhooks never carry

​Next

What this lets you do

`ai_session.classified`

`data` fields

`conversion.attributed`

`data` fields

`webhook.ping`

`data` fields

What webhooks never carry

Next