Webhooks overview

What this lets you do

Push Traceten events into your own systems in real time. When Traceten classifies a session as AI-referred, or attributes a conversion to an AI source, it POSTs a signed JSON payload to an HTTPS endpoint you register. Use it to feed a data warehouse (Snowflake, BigQuery), a CRM (HubSpot, Customer.io), an internal alerting pipeline, or anything else that speaks HTTP.

When to use webhooks

You want to	Use
React to AI sessions in real time, in your own infrastructure	Webhooks
Explore, filter, and chart AI traffic interactively	Dashboard
Send events to Traceten from your backend	Server-side SDKs
Pull aggregates on demand	API

Webhooks are push, not pull. Traceten initiates the request; you only need an endpoint that accepts a POST and returns a 2xx.

Requirements

HTTPS only. Payloads carry your analytics data and endpoints receive a shared signing secret’s output, so plain http:// URLs are rejected at registration.
Publicly reachable. localhost and private-network IPs are rejected. For local development, use a tunnel such as cloudflared or ngrok.
Up to 10 endpoints per site.
Respond fast. Return a 2xx within 10 seconds. Queue heavy work; do not do it inline. See delivery semantics.

The envelope

Every delivery, regardless of event type, is a JSON object with the same five top-level fields:

{
  "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"
  }
}

Field	Type	Description
`id`	string	Delivery id. Stable across retries of the same delivery, so you can use it as an idempotency key.
`type`	string	The event type, e.g. `"ai_session.classified"`. Route on this field.
`api_version`	string	Date-stamped contract version. Currently `"2026-07-01"`.
`created`	integer	Envelope creation time, unix milliseconds.
`data`	object	The event payload. Shape depends on `type`. See the event reference.

All field names are snake_case on the wire, at every level.

Event types

Type	Fires when
`ai_session.classified`	A session on your site is classified as AI-referred. One delivery per AI session.
`conversion.attributed`	A conversion (purchase or custom goal) is attributed to an AI source. One delivery per conversion, with the full four-model breakdown.
`webhook.ping`	You register an endpoint or click Send test event. Never fires as part of your site’s traffic.

Each endpoint subscribes to a list of event types. New endpoints default to ["ai_session.classified"]. Full payloads for every type are in the event reference.

Every delivery is signed

Traceten signs the raw request body with a per-endpoint secret and sends the signature in the X-Traceten-Signature header. Verify it before trusting any payload. See verifying signatures. Requests also carry User-Agent: Traceten-Webhooks/1.0, but the signature, not the user agent, is what proves a request came from Traceten.

Versioning

api_version is date-stamped and changes only for a breaking change to the envelope or to an existing data shape. Additive changes never bump it:

New event types may appear. Ignore type values you do not recognize instead of erroring.
New optional fields may appear inside data. Ignore fields you do not recognize.

Never removed, never renamed: existing event types and existing data fields. Code you ship against "2026-07-01" keeps working.

What webhooks never carry

Payloads are stable projections, not raw internal records. IP hashes, user-agent strings, referrers, and network (ASN) data never leave Traceten, and page URLs are stripped to origin + path. Details are in the event reference.

​What this lets you do

​When to use webhooks

​Requirements

​The envelope

​Event types

​Every delivery is signed

​Versioning

​What webhooks never carry

​Next