Agent webhook tools

A webhook tool is one HTTP endpoint of your own, described once in CommSync. An agent that has the tool can call it while it works on a reply. For example, it can look up an order before it answers "where is my order?", or book a visit when the contact asks for one.

A webhook tool never sends a message. Every reply still goes through the agent's own rules, which include the approval queue in draft mode.

Name and description

The agent reads the name and the description to decide when to call the tool, so write them for the agent:

• Use a plain name in lowercase with underscores, such as check_availability.
• Say what the tool does, and when to call it.
• Say what the agent must never do without it, such as: "Never offer a time it did not return."

Who fills each value

Each path parameter, query parameter, body field, and header gets its value from one source:

The agent sees only the values it fills. For each one, write what the agent puts there, and pick a type: text, number, whole number, or true or false. A text value can have a list of allowed values.

Put a value that changes per call in the path with braces, such as https://api.example.com/orders/{order_id}. CommSync adds a path parameter for each one.

Variables

CommSync knows these values for every call:

A fixed value or a header can include a variable in double braces, such as {{system__line}}.

Keep values on the conversation

A tool can keep a value from its response on the conversation, such as the customer id from a lookup. The value becomes a variable that later calls can send, in the same turn and in later turns of the same conversation. Another agent that takes over the conversation can read it too.

Use this for ids. The agent never has to type an id, so it cannot invent one. When a tool needs a variable that the conversation does not have yet, the agent learns which tool sets it.

Retry if it fails

Retry if it fails is on by default. CommSync then tries the call once more after a short outage, such as a timeout or a 503 answer.

Turn it off for a tool that books, creates, or cancels something. A failed call of that kind can still have done its work, so CommSync never sends it twice. A tool with retry off also:

• carries an Idempotency-Key header. One input for one message always gives one key, so your API can ignore a repeat.
• runs at most once per turn with the same input.
• tells the agent after a failure that the change can have happened. The agent says that a person will confirm, and does not try again.

What the agent reads back

By default the agent reads the whole response, up to 4,000 characters. List the fields it needs, such as data.slots, to keep it short. The agent then reads only those fields.

When a call fails, the agent reads what went wrong and what to do next. After a 4xx answer it reads the start of your error message, so it can correct the input or ask the contact. After a sign-in failure it does not call the tool again.

Authentication

• Bearer token: CommSync sends Authorization: Bearer <token>.
• Username and password: CommSync sends HTTP Basic authentication.
• OAuth 2.0 client credentials: CommSync gets a token from your token URL. It keeps the token until shortly before it expires, and sends it as a bearer token.
• A secret header: for an API key in a header of your choice.

CommSync encrypts every secret when you save it. CommSync never shows a secret again, and the agent never sees one.

CommSync sends a saved secret only to the address you saved it for. If you change the scheme, the host, or the port of the URL, type each secret again before you save or test. The same rule applies to the client secret when you change the token URL. The editor marks each secret field that needs a new value. A change to the path or the query keeps the saved secrets.

Check that a call came from CommSync

Every request carries these headers:

CommSync signs <t>.<METHOD>.<path and query>.<body> with HMAC-SHA256 and the tool's signing secret. CommSync shows the signing secret once when you create the tool, and once each time you rotate it.

import { createHmac, timingSafeEqual } from 'node:crypto';

function fromCommSync(req: { method: string; url: string; headers: Record<string, string>; rawBody: string }, secret: string) {
  const parts = Object.fromEntries(req.headers['x-commsync-signature'].split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${req.method.toUpperCase()}.${req.url}.${req.rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Here req.url is the path and the query string, such as /orders/1043?v=2.

Limits and safety

• A workspace holds up to 50 webhook tools, and one agent carries up to 20.
• The wait for an answer is 1 to 30 seconds. The default is 10.
• One turn makes at most 4 calls of one tool and 8 webhook calls in total.
• CommSync reads at most 256 KB of a response.
• CommSync calls only public addresses. It never follows a redirect.
• Production tools must use https.
• A tool can never message anyone.

Activity and health

The agent's Activity tab shows each call: "Checked lookup_order", "Changed data with book_visit", or "lookup_order did not work", with the reason. The Webhooks page shows the last answer and its time for each tool, so a broken endpoint is easy to see. A test does not count as a call.