> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traceten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Receive AI-classified sessions and AI-attributed conversions as signed HTTPS POSTs to your own endpoint, the moment they happen.

## 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](/dashboard/overview)   |
| Send events *to* Traceten from your backend                   | [Server-side SDKs](/sdks/overview) |
| Pull aggregates on demand                                     | [API](/api/authentication)         |

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](/webhooks/delivery).

## The envelope

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

```json theme={null}
{
  "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](/webhooks/events).          |

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](/webhooks/events).

## 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](/webhooks/verify-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](/webhooks/events#what-webhooks-never-carry).

## Next

* [Set up your first endpoint](/webhooks/setup)
* [Verify signatures](/webhooks/verify-signatures)
* [Event reference](/webhooks/events)
* [Delivery semantics](/webhooks/delivery)