Katexs
Reliability and idempotency

Webhooks & events

Reliability and idempotency

How Katexs handles duplicates, retries and failures, and how your endpoints should too.

How Katexs processes events

Webhook processing pipeline Each event is received, its secret verified, its event key claimed to drop duplicates, its workspace resolved and matched, then handled and recorded. Failures exit early with a 401, a duplicate acknowledgement, or an ignored response. 1. ReceivePOST + raw body 2. Verifyshared secret 401Invalid signature 3. Claimevent key, dedupe 200duplicate: true 4. Resolveworkspace match 200ignored, mismatch 5. Handlelog, bill, tools 6. Recorddone or failed Every event, in order Tool calls skip step 3 so a live caller always gets an answer.
How Katexs processes every voice event before anything is billed or stored.
  1. 1

    Receive

    the raw body is read before parsing, so signatures can be checked byte for byte.

  2. 2

    Verify

    requests without the shared secret are rejected with 401 and the rejection is recorded for diagnosis.

  3. 3

    Claim

    each event gets a key from its type, the call id and, for status updates, the status. A key can only be claimed once, so redelivered events are acknowledged with { "ok": true, "duplicate": true } and not processed again.

  4. 4

    Resolve

    the workspace is found from the agent and checked against the workspace tag on the event. If they disagree, the event is ignored and logged.

  5. 5

    Handle

    the call log, billing, memory and notifications are updated.

  6. 6

    Record

    the event is marked done or failed with a note.

Tool requests skip the claim step: a live caller must always get an answer, even if the same request arrives twice.

Billing exactly once

Calls are charged by a single database operation that locks the workspace, prices the call from the workspace's own rate, and records at most one charge per call id. If charging fails, Katexs releases the event so a redelivery bills it, and the per-call guard makes sure it's never billed twice.

What your endpoints should do

  • Be idempotent — key side effects on the tool call id or call id.
  • Answer before doing slow work — for anything slow, accept, queue and return. See Latency and async tools.
  • Don't depend on order — informational events can arrive late or more than once. Use the call id and status to decide, not arrival order.
  • Return 2xx only when you've succeeded — a 2xx tells the agent the action happened.

Last updated November 2026 · Found a problem? Email support@katexs.com