Webhooks & events
Reliability and idempotency
How Katexs handles duplicates, retries and failures, and how your endpoints should too.
How Katexs processes events
- 1
Receive
the raw body is read before parsing, so signatures can be checked byte for byte.
- 2
Verify
requests without the shared secret are rejected with
401and the rejection is recorded for diagnosis. - 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
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
Handle
the call log, billing, memory and notifications are updated.
- 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
