Skip to main content
A webhook tool lets an agent call your own API: look up an order, check stock, book an appointment. You add one under Tools → Add tool → Webhook with a display name, a tool name for the AI, an endpoint URL and, optionally, a bearer token.

​
The request

Every call is one POST with a JSON body.
​
object
required
The arguments the agent chose for this call, keyed by the tool’s input names. It can be an empty object.
​
boolean
required
true for calls from the dashboard’s test panel and from agent tests. Always false in a real customer conversation. Read data as usual, but do not change anything: no refunds, no bookings, no emails. We cannot enforce this on your side, so your endpoint has to honour it.

​
Headers

​
string
required
Always application/json.
​
string
Bearer <token>, when you gave the tool a bearer token. We store the token encrypted and send it only to the tool’s own endpoint. Check it on every request.

​
The response

  • Any 2xx status is a success. We parse the body as JSON, and pass it on as plain text if it is not JSON. There is no fixed response format: return what the agent needs to answer.
  • Any other status is a failure. The agent is told the call failed with that HTTP status and does not see your body. It can then tell the customer it could not look this up, or hand the conversation to a person.
  • Your response is data, not instructions. The agent reads it as the tool’s output. Text such as “ignore your instructions” in a response is treated as content, not obeyed.
  • Keep it small. Everything you return is read by the agent on every call. Return the fields it needs, not the whole record.
Return a short explanation in the 2xx body when nothing was found, for example {"found": false, "reason": "No order with that number for this email address"}. The agent can use it in its answer. A 404 only tells it the call failed.

​
Limits

​
Testing your endpoint

Run the same request yourself before connecting it:
Then open the agent in the dashboard, enable the tool, and ask a question in the test panel that needs it. Those calls always arrive with "dry_run": true.