Set up a webhook endpoint

What this lets you do

Go from nothing to a live, verified webhook endpoint receiving signed Traceten events.

Before you start

A Traceten account with at least one site tracked.
An HTTPS endpoint that is publicly reachable. http://, localhost, and private-network IPs are rejected at registration. For local development, expose your machine with a tunnel such as cloudflared or ngrok and register the tunnel URL.

Set up the endpoint

Deploy a handler that returns 2xx fast

Your endpoint receives a POST with a JSON body. Read the raw body, acknowledge with a 2xx, and queue any heavy work. Traceten times out after 10 seconds and treats a timeout as a failed delivery.A minimal handler that accepts everything (you will add signature verification in step 4):

import express from "express";

const app = express();

app.post("/traceten-webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const event = JSON.parse(req.body.toString("utf8"));
  console.log(`received ${event.type} (${event.id})`);
  res.status(200).end();
});

app.listen(3000);

Note express.raw, not express.json. You need the raw body bytes to verify signatures later.

Go to app.traceten.com, open Settings → Webhooks, and click Add endpoint. Choose the Site the endpoint receives events from (it starts on the site you are viewing), enter the HTTPS URL, and choose the event types to subscribe to. New endpoints default to ai_session.classified. Each site can have up to 10 endpoints, and every endpoint in the list shows which site it belongs to.On registration, Traceten immediately sends a signed webhook.ping to the URL. If your endpoint answers with a 2xx, it is marked Verified right away. If it does not (for example, you registered the URL before deploying the handler), the endpoint is created anyway and marked Unverified; a failed registration ping never blocks creation. See verification status below.

Capture the signing secret

On creation, Traceten shows the endpoint’s signing secret once. Copy it now and store it where your handler can read it, such as an environment variable:

export TRACETEN_WEBHOOK_SECRET="whsec_..."

If you lose it, you cannot view it again. Use Rotate secret on the endpoint detail page to generate a new one. Rotation is immediate: the old secret stops working the moment the new one is issued, so update your handler’s configuration in the same change.

Add signature verification

Before trusting any payload, verify the X-Traceten-Signature header against the raw body using your signing secret. Follow verifying signatures for working Node, Python, and Go code, then confirm your implementation against the published conformance vector on that page.

Send a test event

On the endpoint detail page, click Send test event. Traceten delivers a signed webhook.ping through the real signing and delivery path and shows the result inline: status code, latency, and a snippet of your response. A 2xx marks the endpoint Verified. Test deliveries appear in the delivery log with a Test badge.Test events work on disabled endpoints too, so you can verify an endpoint before enabling it. The button is rate-limited to 10 sends per minute per endpoint (30 per minute across all your endpoints), and each test gets a single attempt (no retries).You are live when the test event returns a 2xx and your handler’s signature verification passes on it.

Verification status

Every endpoint carries a verification status, shown as a badge next to the endpoint in Settings → Webhooks. It reflects the outcome of the most recent webhook.ping (registration or Send test event); real event deliveries do not change it.

Status	Meaning
Verified	The most recent ping got a 2xx. The endpoint has proven it can receive and acknowledge a signed delivery.
Unverified	No ping has ever succeeded. Typical for an endpoint registered before its handler was deployed.
Verification failing	The endpoint was verified at some point, but the most recent ping failed. Something that used to work is now broken.

The transitions are simple: any successful ping moves the endpoint to Verified (including from Verification failing), and a failed ping moves a Verified endpoint to Verification failing. An Unverified endpoint stays Unverified on further failures; it was never proven, so there is nothing to demote. Verification status is a diagnostic, not a gate. Traceten delivers real events to an enabled endpoint regardless of its verification status.

Verify it worked

Click Send test event on the endpoint detail page.
The inline result shows a 2xx status.
Your handler logs a received webhook.ping that passed signature verification.

From this point, real ai_session.classified deliveries arrive as your site’s AI traffic is classified. If the site is new or low-traffic, that can take a while; the test event is the proof the pipe works.

Troubleshooting

Registration rejects the URL. The URL must be https:// and publicly resolvable. http://, localhost, 127.0.0.1, and private IP ranges are rejected. Use a tunnel for local development. Endpoint shows Unverified after registration. The registration ping did not get a 2xx, usually because the handler was not deployed yet. Deploy it, then click Send test event; a 2xx flips the endpoint to Verified. Endpoint shows Verification failing. A previously working endpoint failed its most recent test ping: it returned a non-2xx, took longer than 10 seconds, or was unreachable. Check that the route still accepts POST at the exact registered path and responds before doing heavy work, then re-send a test event to re-verify. Send test event returns a rate-cap error. Test sends are limited to 10 per minute per endpoint (30 per minute across all endpoints), and a ping can also be deferred by the endpoint’s own delivery rate cap. Wait a moment and click again; a rate-capped ping proves nothing about the endpoint and does not change its verification status. Signature verification fails on every delivery. Almost always a raw-body problem: a framework middleware parsed and re-serialized the JSON before your code hashed it. See the raw body rule. Signature verification fails after rotating the secret. Rotation invalidates the old secret immediately. Update the secret in your handler’s environment and redeploy. No real events arrive, but test events work. The pipe is fine; the site has no classified AI sessions yet. Check the dashboard for AI traffic on that site, and confirm the endpoint subscribes to ai_session.classified and is enabled.

​What this lets you do

​Before you start

​Set up the endpoint

​Verification status

​Verify it worked

​Troubleshooting

​Next