Webhooks

Registering a webhook

Via the admin console Integrations panel:

URL:     https://your-endpoint.com/tokenone-webhook
Events:  llm.call, stage.changed
Secret:  <auto-generated HMAC-SHA256 signing key>

Or via API:

POST /api/webhooks
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "url": "https://your-endpoint.com/tokenone-webhook",
  "events": ["llm.call", "stage.changed"],
  "description": "Forward TokenOne Delivery® events to our data warehouse"
}

Delivery shape

POST <your URL>
Content-Type: application/json
X-TokenOne®-Event: llm.call
X-TokenOne®-Delivery: <uuid>
X-TokenOne®-Signature: sha256=<hex>

{
  "type": "llm.call",
  "projectId": "...",
  "tenantId": "...",
  "actorUserId": "...",
  "at": "2026-04-19T22:34:12.000Z",
  "payload": { /* event-specific */ }
}

Signature verification

Compute HMAC-SHA256(secret, raw_body) and compare to the X-TokenOne®-Signature header (strip the sha256= prefix). Reject mismatches.

import { createHmac, timingSafeEqual } from 'crypto';

const expected = 'sha256=' + createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');

const actual = req.headers['x-tokenone-signature'];
if (!timingSafeEqual(Buffer.from(actual), Buffer.from(expected))) {
  throw new Error('Bad signature');
}

Retries

Non-2xx responses are retried with exponential back-off (1m, 5m, 30m, 2h, 12h, then dropped after 6 attempts). Inspect failures via the admin console webhook dashboard.

Replay

Every delivery is logged for 30 days. Resend any failed delivery via POST /api/webhooks/deliveries/:id/replay.