What stays where
Be precise about this when you explain it to your own customers.1. Build the endpoints
Small and single-purpose — each one becomes one thing the agent can do.- https only. Addresses inside private networks are refused.
- Authenticate with a header you choose, e.g.
Authorization: Bearer <secret>. We store it sealed and never show it again. - Answer within 10 seconds — callers on the phone are waiting.
- Return only what the agent needs. It reads about 4,000 characters of the answer; an order’s status, not the order history.
- Treat every argument as untrusted — it came from a stranger’s message. Use parameterised queries and never let an argument pick a table or a URL.
2. Connect them
Ask your assistant, or do it step by step:create_action— name (get_order), a description of when to call it (the agent decides from this sentence alone), the URL with placeholders, one parameter per placeholder, and your auth header.test_actionwith sample arguments — a real call, through the same path the agent uses. Fix errors now, not when a customer is waiting.enable_action— after your approval it goes live for everyone talking to the agent.update_agent— tell the agent about it in its instructions: “Look up the order with get_order before answering anything about delivery.”
3. Receive what happens
create_webhook with your endpoint and the events you want. The answer contains
a signing secret, once — store it in your receiver’s environment.
Every delivery is a POST of { "id", "event", "sentAt", "data" } — id is the
event’s evt_… id — with the header
x-thinnest-signature: sha256=<HMAC-SHA256 of the raw body>. Verify the raw
bytes before parsing:
Each attempt also carries
x-thinnest-event-id, x-thinnest-attempt,
x-thinnest-delivered-at and x-thinnest-signature-v2 (the delivery time,
signed). A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2
hours and 6 hours, so dedupe on x-thinnest-event-id: a retry can reach you
after you already handled the first attempt. Answer 2xx quickly and do the work
after. The full contract is in Webhooks.
| contact.opted_out | A caller asked not to be called again; their number is now on your do-not-call list |
Each attempt also carries x-thinnest-event-id, x-thinnest-attempt,
x-thinnest-delivered-at and x-thinnest-signature-v2 (the delivery time,
signed). A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2
hours and 6 hours, so dedupe on x-thinnest-event-id: a retry can reach you
after you already handled the first attempt. Answer 2xx quickly and do the work
after. The full contract is in Webhooks.
To keep chat transcripts in your database today, fetch the messages
(list_messages) when conversation.resolved or conversation.escalated
arrives.