Webhooks & events
Securing your endpoint
Protect the HTTPS endpoints that receive tool requests from your agents.
Today
Tool requests to your endpoint are not yet signed. Until signed requests ship, protect your endpoint like this:
- 1
Use an unguessable URL
Put a long random token in the path, for example
https://api.example.com/katexs/fn/4f9c1e7b2d.../order-status. Treat the URL as a secret: don't log it, don't commit it, rotate it if it leaks. - 2
Validate the payload
Parse the body with a strict schema (for example Zod). Reject anything that isn't a
tool-callsmessage with the arguments you expect. - 3
Authorize on your side
Never let a tool argument decide what data someone may see. Look the caller up by the call's customer number or by a code they give, and apply your own rules.
- 4
Make it idempotent
Use the tool call
idas an idempotency key so a retried request doesn't create a second order or booking. - 5
Limit what it can do
Give the endpoint only the permissions the tool needs. A status lookup should not be able to issue refunds.
- 6
Log with context
Log the call id, tool call id, function name, outcome and latency. Never log full payment or health data.
Signed requests (Preview)
Signed requests will add a signature header on every request, an HMAC-SHA256 over a timestamp and the raw body using a per-workspace secret, with a short replay window. Verify the signature over the raw bytes before parsing, compare in constant time, and reject old timestamps. Ask support@katexs.com to join the preview.
What Katexs does on its side
- Refuses to call URLs that aren't HTTPS, contain credentials, or point at internal hosts, private networks or cloud metadata addresses.
- Never follows redirects.
- Reads at most 16 KB of your response and passes at most 1000 characters to the agent.
- Rate-limits tool calls per workspace.
- Verifies every event it receives from the voice engine with a shared secret, and rejects unsigned requests with
401.
Last updated November 2026 · Found a problem? Email support@katexs.com
