Webhook tools

Connect your voice agent to external applications during a call. A webhook tool can look up an order, check appointment availability, create a support ticket, or submit a callback request. The agent supplies the configured parameters, Cartra calls your HTTP endpoint, and the endpoint's response becomes available to the agent.

Webhook tools are configured by Cartra platform owners. If you do not see the Tools tab, contact your Cartra team to set up the integration. Your application administrator can prepare the endpoint and credentials using this guide.

Choose the right integration#

A webhook tool runs when the agent invokes it, not automatically on every call. It does not automatically send the transcript, caller number, call ID, or post-call event payload. Its request contains the parameters and headers you configure.

There are two ways to connect an external application:

• Call its API directly when it accepts the supported request format and authentication headers.
• Use a small integration service when you need to transform data, call several applications, refresh OAuth credentials, or construct a nested request. Cartra calls that endpoint; it handles the application-specific work and returns a concise result.

Before you start#

Prepare:

• An endpoint reachable from the public internet. Use HTTPS, especially when sending credentials or customer information.
• The HTTP method, required fields, and authentication requirements.
• A test account or sandbox in the external application.
• A response that tells the agent what actually happened.

For example, an order lookup should return the order status. A workflow that only queues a callback should return that it was accepted, rather than claiming the callback has already happened.

The default timeout is 10 seconds, configurable from 1 to 30 seconds. Design the integration to respond within that window, including all downstream application calls. Optionally enable Generate speech when calling this tool so the agent speaks a brief line from your instruction while the request runs. The HTTP request starts immediately and does not wait for that speech to finish.

Set up a tool in Cartra#

1. Open the agent in the dashboard and select Tools → Webhook Tools.
2. Select Add webhook tool. New tools start disabled.
3. Enter a unique Tool name, such as lookup_order, and a Description explaining when the agent should use it and what it returns.
4. Enter the endpoint URL, HTTP method, and Timeout (seconds).
5. Add any fixed Headers, such as Authorization: Bearer YOUR_API_TOKEN. Header values are masked until you select Reveal.
6. Add Parameters for the values the agent should supply.
7. Optionally enable Generate speech when calling this tool and enter a Speech instruction for what the agent should say while the request runs. The agent calls the tool silently; testing does not generate speech.
8. Optionally set Available during procedure to one Procedure. The tool stays hidden until that Procedure is active. Leave Always available if the tool should remain in the tool list for the whole call.
9. Fill in sample values under Test unsaved settings, then select Send test request.
10. Check both the result shown in Cartra and the external application's records.
11. Enable the tool and select Save Changes. Saved changes apply to the next call; a test does not save or enable the tool.

Send test request sends a real request. It can create records, send notifications, or change data in the connected application. Use sample data and an application sandbox before testing actions against live accounts.

Give the agent instructions explaining when to invoke the tool, which values to collect, and how to handle failure. For example:

When a caller asks about an order, ask for their order ID and use lookup_order. Report the returned status. If the lookup fails, explain that you could not retrieve the order and offer the next support step.

If the agent uses Tasks, select the enabled webhook in the relevant task's tool list. Adding a tool does not automatically select it for an existing task.

Tool names must begin with a letter or underscore and contain only letters, digits, and underscores, up to 64 characters. Names must be unique and cannot reuse built-in tool names, including start_procedure, resume_procedure, and stop_procedure. Renaming or deleting a tool may require updates to agent instructions, task selections, and dynamic-variable assignments.

Configure request parameters#

Each parameter has a name, description, type, location, and required flag. Use its description to explain the expected value, such as “the order ID provided by the caller.”

Path parameters must be required and match the URL placeholders exactly. Query and body parameters can be optional; omitted values are not sent.

Supported types are string, number, integer, and boolean. Use strings for phone numbers, postal codes, and IDs that can have leading zeros. Query flags must use strings such as "true" or "false"; boolean query parameters are not supported.

Available methods are GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. JSON body parameters are supported only for POST, PUT, and PATCH. For a lookup that needs a returned body, use the application's GET or POST endpoint rather than HEAD.

The editor supports flat JSON body fields. It does not build nested objects, arrays, multipart uploads, or form-encoded bodies. Headers are fixed values; the editor does not interpolate session variables into headers or provide an OAuth sign-in flow. Use an integration service for those requirements.

Example: look up an order through an API#

The following URL and data are illustrative. Replace them with your application's endpoint and credentials.

Add one parameter:

Testing with ORD-1042 sends a GET request to:

https://api.example.com/orders/ORD-1042

The application should return a 2xx response with Content-Type: application/json and a useful result, for example:

{
  "found": true,
  "order_id": "ORD-1042",
  "status": "shipped",
  "estimated_delivery": "2026-09-15"
}

A successful HTTP response means the HTTP request succeeded. The agent should also inspect the returned business result: {"found":false} does not mean an order was found.

Example: submit a callback to an external application#

Create a request_callback tool pointing to your application's endpoint or your integration service, with method POST. Add these body parameters:

The endpoint receives a JSON body like:

{
  "customer_name": "Alex",
  "phone_number": "+12025550123",
  "reason": "Discuss an appointment"
}

Your integration maps these fields into the connected application's contact, ticket, or callback fields. It should authenticate the request and validate the values before writing a record.

If the record was created, return a result such as:

{
  "status": "created",
  "request_id": "CB-2048",
  "message": "The callback request has been recorded."
}

If work will happen later, return an honest acknowledgement such as {"status":"accepted","message":"Your request has been queued."}. Instruct the agent to confirm only the outcome the endpoint actually returned.

Responses, authentication, and retries#

Return application/json or a text/* content type. Keep the response concise: the agent sees up to 2,000 characters of a successful response. Put the outcome and essential details first. Binary responses are not usable as tool results.

The test panel displays HTTP status, elapsed time, response text, and an agent-visible preview. Test response capture is limited to 64 KiB, with truncation indicated separately from the shorter agent preview.

Configure the final endpoint URL directly. Dashboard tests reject redirects and private network destinations; in-call requests may follow redirects. A passing test checks request execution, not whether the agent will choose the tool or whether the business action is correct. Always finish with a new test call.

Webhook tools do not use the signing headers or retry delivery system described in the post-call webhook guide. Configure the authentication your endpoint expects, using headers where supported. Keep application credentials out of tool descriptions, agent instructions, and response bodies.

There is no automatic HTTP retry for a webhook tool invocation. The agent or a user can invoke it again. For actions that create records, make the receiving application safe to call repeatedly. A timeout does not prove the action failed: check the application's records before repeating it. The tool does not automatically supply a stable request ID for deduplication.

Troubleshooting#