Webhooks API - Traceten

What this covers

Managing the endpoints Traceten sends events to. If you want to know what those events look like or how to verify their signatures, start with the Webhooks guide.

https://api.traceten.com/v1/sites/{siteId}/webhooks

{siteId} is your snippet key (ttid_…) when you authenticate with an API key. Reading needs stats:read. Registering a webhook and rotating its secret need credentials:write, because both hand back a signing secret. Editing, deleting and testing need config:write.

`GET /v1/sites/{siteId}/webhooks`

curl https://api.traceten.com/v1/sites/ttid_7Rb4TrC1dTbnD8w3s1TS12/webhooks \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "webhooks": [
    {
      "id": "9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61",
      "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
      "url": "https://hooks.example.com/traceten",
      "event_types": ["ai_session.classified"],
      "enabled": true,
      "verification_status": "verified",
      "created_at": "2026-07-04T12:00:00.000Z",
      "updated_at": "2026-08-12T09:31:20.000Z"
    }
  ]
}

Signing secrets are never in a listing. They appear only when you create an endpoint or rotate its secret. verification_status is diagnostic:

Value	Meaning
`verified`	A ping reached this endpoint and it answered 2xx.
`failing`	It was verified once and a later ping failed.
`unverified`	No ping has ever succeeded. It may simply not be live yet.

`POST /v1/sites/{siteId}/webhooks`

curl -X POST https://api.traceten.com/v1/sites/ttid_7Rb4TrC1dTbnD8w3s1TS12/webhooks \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/traceten",
    "event_types": ["ai_session.classified"]
  }'

{
  "id": "9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61",
  "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  "url": "https://hooks.example.com/traceten",
  "event_types": ["ai_session.classified"],
  "enabled": true,
  "verification_status": "verified",
  "created_at": "2026-08-29T12:04:44.000Z",
  "updated_at": "2026-08-29T12:04:44.000Z",
  "secret": "whsec_EXAMPLE"
}

secret is returned once, here. Store it before you discard the response. No read endpoint can give it back.

url must be https://, must not embed credentials, and must not point at a private, loopback or internal address. event_types defaults to ["ai_session.classified"]. Registration sends one real ping through the delivery path, which is why verification_status is often already verified in this response. A failed ping does not block creation, it just leaves the endpoint unverified. Ten webhooks per site.

`PATCH /v1/sites/{siteId}/webhooks/{webhookId}`

Send at least one of url, event_types, enabled.

curl -X PATCH https://api.traceten.com/v1/sites/ttid_7Rb4TrC1dTbnD8w3s1TS12/webhooks/9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61 \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Returns the updated webhook.

`DELETE /v1/sites/{siteId}/webhooks/{webhookId}`

Removes the endpoint and its delivery log. Returns 204 with no body. Unlike site deletion this is immediate; there is no window and no restore.

`GET /v1/sites/{siteId}/webhooks/{webhookId}/deliveries`

curl "https://api.traceten.com/v1/sites/ttid_7Rb4TrC1dTbnD8w3s1TS12/webhooks/9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61/deliveries?limit=50&status=failed" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "deliveries": [
    {
      "id": "5b2e8c14-9f03-4a67-8d51-1c7b0e4a2f38",
      "webhook_id": "9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61",
      "event_type": "ai_session.classified",
      "envelope_id": "whd_2f7a5c9e-3d61-4e88-b014-9d3c1f706a25",
      "dedupe_key": "sess_8a3f0c15d2e947b6",
      "status": "failed",
      "attempt_count": 5,
      "response_status": 500,
      "last_error": "HTTP 500",
      "next_attempt_at": null,
      "last_attempt_at": "2026-08-29T10:02:41.118Z",
      "created_at": "2026-08-29T09:44:02.000Z",
      "payload": "{\"id\":\"whd_2f7a5c9e...\"}"
    }
  ],
  "next_before": "2026-08-29T09:44:02.000Z"
}

Newest first. Pass the previous page’s next_before back as before to page. next_before is null when the page was not full.

Parameter	Type	Notes
`limit`	integer	1 to 100. Defaults to 50.
`status`	string	`pending`, `retrying`, `succeeded` or `failed`.
`before`	string	ISO-8601 cursor.

Test pings appear in this log with event_type: "webhook.ping". Exclude them before you compute a success rate, or your own test sends will skew it.

`POST /v1/sites/{siteId}/webhooks/{webhookId}/test`

Sends one signed ping through the same path as real events and returns the outcome inline. Allowed on a disabled webhook, so you can prove an endpoint before switching it on.

{
  "ok": true,
  "status_code": 200,
  "latency_ms": 142,
  "response_snippet": "OK",
  "verification_status": "verified"
}

A ping is terminal after one attempt; it never enters the retry schedule. A 429 means the endpoint is currently rate-capped, nothing was proved either way, and verification_status is untouched. Click again in a moment.

The ping payload we deliver to your endpoint carries site_id as the site’s internal UUID, not the snippet key you used in the request URL. That is a property of the outbound webhook contract rather than this API, and it differs from ai_session.classified and conversion.attributed, which carry the ttid_. See event payloads.

This needs config:write, not stats:read. It causes Traceten to make a real outbound request on your behalf, which is not a read.

`POST /v1/sites/{siteId}/webhooks/{webhookId}/rotate-secret`

{
  "id": "9d3c1f70-6a25-4e88-b014-2f7a5c9e3d61",
  "secret": "whsec_EXAMPLE_ROTATED"
}

Destructive. The old secret stops verifying immediately. There is no overlap window, so any receiver still checking against the old value will reject every delivery until you deploy the new one. Deploy a receiver that accepts both, rotate, then remove the old one.

The new secret is returned once, here.

Errors

Status	`error`	Cause
`401`	`unauthorized`	Missing, malformed, revoked or expired key.
`403`	`insufficient_scope`	The key lacks the permission this endpoint needs. `required_scope` names it.
`403`	`Forbidden`	The site is not one this credential can reach, or it is inside its deletion window.
`404`	none	Unknown webhook id on that site.
`422`	`validation_failed`	Bad URL or body.
`429`	none	On `test`, the endpoint is rate-capped.

​What this covers

​GET /v1/sites/{siteId}/webhooks

​POST /v1/sites/{siteId}/webhooks

​PATCH /v1/sites/{siteId}/webhooks/{webhookId}

​DELETE /v1/sites/{siteId}/webhooks/{webhookId}

​GET /v1/sites/{siteId}/webhooks/{webhookId}/deliveries

​POST /v1/sites/{siteId}/webhooks/{webhookId}/test

​POST /v1/sites/{siteId}/webhooks/{webhookId}/rotate-secret

​Errors

​Next

What this covers

`GET /v1/sites/{siteId}/webhooks`

`POST /v1/sites/{siteId}/webhooks`

`PATCH /v1/sites/{siteId}/webhooks/{webhookId}`

`DELETE /v1/sites/{siteId}/webhooks/{webhookId}`

`GET /v1/sites/{siteId}/webhooks/{webhookId}/deliveries`

`POST /v1/sites/{siteId}/webhooks/{webhookId}/test`

`POST /v1/sites/{siteId}/webhooks/{webhookId}/rotate-secret`

Errors

Next