Server URLs

A server URL is any HTTPS endpoint you control that Katexs posts events to. You can set one for the whole workspace, override it per agent, and point a separate URL at live control responses.

Set a workspace URL

1. 1

   Open Settings → Integrations

   Find the Webhooks card and click Add server URL.

2. 2

   Paste your HTTPS endpoint

   HTTP is rejected. Self-signed certificates are rejected.

3. 3

   Select events

   Subscribe only to what you use. Fewer events means less noise and lower retry pressure.

4. 4

   Send a test event

   Katexs posts a signed sample payload and shows the exact response it got back.

Scopes and precedence

Endpoint requirements

• HTTPS with a valid certificate — TLS 1.2 or higher.
• Respond within 5 seconds — Return 2xx fast and do the real work asynchronously.
• Accept POST with JSON — Content-Type is always application/json; UTF-8.
• Be idempotent — Retries happen. Deduplicate on the event id.

Minimal receiver

export async function POST(request: Request) {
  const raw = await request.text();
  if (!verifySignature(raw, request.headers.get("x-katexs-signature"))) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(raw);
  await queue.push(event);        // do the work off the request path
  return new Response("ok");      // respond immediately
}

Custom headers

Add static headers if your gateway requires them — an API key, a tenant ID, or a routing hint. Values are stored encrypted and never appear in logs.

{
  "server_url": "https://api.example.com/katexs/events",
  "headers": {
    "X-Tenant-Id": "acme",
    "X-Gateway-Key": "{{secret:GATEWAY_KEY}}"
  },
  "events": ["call.started", "call.ended", "tool.called", "insights.ready"]
}

Retries and delivery

Non-2xx responses and timeouts are retried five times with exponential backoff over roughly 15 minutes. After the final failure the event is marked undelivered and appears under Observability → Logging, where you can replay it.