Skip to main content

​
API & Webhooks

The API & Webhooks tool is the single way to connect an agent to anything that speaks HTTP — your own backend, a CRM, or an automation platform. It has three modes; pick the one that matches what the agent needs to do.

API Endpoints

Define endpoints (or import an OpenAPI spec). Each becomes a function the agent can call by name — get_doctors, book_appointment. Use when the agent must read or write data in your system.

Webhook

Fire-and-forget: POST conversation data to a Zapier / Make.com / n8n / custom URL. The agent does not read the response. Use to trigger an automation.

Free-form Request

The agent composes its own GET/POST requests under a base URL. Use only when you cannot define the endpoints up front.
This tool replaces the older separate Webhook, REST API, Custom API, Make.com, and n8n tiles. Agents saved with those still work — they load as the matching mode.
The agent gets one named, typed function per endpoint, so a voice or chat agent in any language can call get_slot_availability(doctor_id, date) directly instead of constructing raw HTTP.

​
Set the base URL and auth

FieldWhat it is
API NameFriendly name shown to the agent, e.g. “Hospital Booking API”.
Base URLPublic HTTPS root, e.g. https://api.yourhospital.com. localhost, private IPs, and plain HTTP are blocked for security.
Auth TypeAPI Key Header (e.g. X-API-Key: <key>), Bearer Token (Authorization: Bearer <key>), Basic Auth, or none.
Default HeadersOptional JSON object sent on every request.
Your API must be reachable from the public internet over HTTPS with a valid certificate. If your spec says https://localhost/..., deploy to a public host first — the platform cannot reach your local machine.

​
Define endpoints

Each endpoint needs:
  • Function name — what the agent calls: get_doctors, create_appointment.
  • Method + Path — GET /api/doctors, POST /api/appointments. Use {braces} for path variables: /api/slot/{doctor_id}/availability.
  • Description — tells the agent when to use it: “Get available appointment slots for a doctor on a date.”
  • Parameters — name, location (path / query / body), type, required flag, and a description. Good parameter descriptions (“Date in YYYY-MM-DD format”) stop the agent guessing wrong formats.
Example — a hospital appointment API becomes three functions:
FunctionMethod & pathParameters
get_doctorsGET /api/doctorslimit (query, optional)
get_slot_availabilityGET /api/slot/{doctor_id}/availabilitydoctor_id (path), date (query)
create_appointmentPOST /api/appointmentspatient_id, doctor_id, slot_id (body)

​
Import from OpenAPI

Click Import OpenAPI, paste your OpenAPI 3.x or Swagger 2.0 JSON, and the endpoints are generated automatically — operation IDs become function names, summaries become descriptions, and path/query/body parameters are mapped with their types. Edit anything after import.

​
Test the connection

Click Test Connection. The platform probes your API with the configured auth and tells you exactly what happened — including a specific message when the URL is reachable but the key is rejected (HTTP 401/403), so auth problems surface before your first live call.

​
Tell the agent when to act

When a caller wants an appointment: call get_doctors to find the doctor,
get_slot_availability for their requested date, read the open slots back to
the caller, and once they pick one call create_appointment. Never invent
doctors, slots, or IDs — always read them from the API.

​
Mode 2 — Webhook

Fires a single POST to one URL when the agent decides something noteworthy happened (lead captured, appointment booked, ticket raised). The platform receiving it — Zapier, Make.com, n8n, or your own endpoint — does the rest.
  1. In your automation platform, create a trigger that starts with an incoming/custom webhook and copy its URL.
  2. Add the API & Webhooks tool, choose Webhook mode, and paste the URL.
  3. (Optional) Set a secret — sent as X-Webhook-Secret — or custom headers (e.g. X-API-Key) for endpoints that need auth.
  4. Tell the agent when to fire it, e.g. “After booking, send a appointment_booked event with the caller’s name and slot.”
Platform-specific setup: Make.com · n8n.

​
Mode 3 — Free-form Request

The agent composes its own requests under a base URL using a single make_request function. This is the most flexible but least guided option — prefer API Endpoints mode whenever you can list the endpoints, because named functions are far more reliable for the model (especially in voice).

​
Limits and behavior

  • API Endpoints: up to 25 endpoints per tool, 30 parameters each.
  • Responses return to the agent as {status_code, data} JSON, truncated at ~4,000 characters — prefer limit/pagination parameters for large collections.
  • Timeouts are configurable (1–120 s, default 15 s). Keep voice agents under ~10 s.
  • All requests are SSRF-guarded: URLs are validated and re-resolved against private/reserved IP ranges.

​
Troubleshooting

SymptomLikely cause
”authentication failed (HTTP 401/403)“Wrong Auth Type or header name — check whether your API expects X-API-Key or Authorization: Bearer.
”Only HTTPS URLs are allowed”Base/target URL uses http:// or points to localhost / a private IP.
Agent says it acted but nothing happenedA required parameter was missing — the function returns an error the agent may paraphrase. Check the call’s tool traces.
Responses cut offBody exceeded the ~4,000-character budget. Add pagination/limit parameters.

​
Using HTTP inside flows and workflows

  • Flow Editor: drop an HTTP Request node onto the canvas to call an API at a specific step and pass the response to the next node.
  • Voice Workflows (state machines): an API Request step calls an API mid-call and maps response fields into workflow variables for later branches.
Both use the same engine (auth, SSRF guard, response shaping) as this tool.