> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & webhooks

> Give assistants tools during calls, and receive results after them

## Central tool registry

Create API, MCP, and built-in tools once on the **Tools** page. Assistants and
flows only reference these central definitions, so changing a tool updates
every assigned assistant and flow without adding it again.

* Assign or remove tools in **Assistant → Settings → Tools**.
* Add API and built-in tools directly from the Flow Builder's searchable
  **Add node** library. The builder creates the matching node automatically.
* Tool-node settings contain only flow-specific routing. Endpoint, auth,
  transfer destination, prompt, and other shared settings stay on **Tools**.
* MCP entries represent an entire server and are therefore assistant-wide,
  rather than a single deterministic flow node.

There is no inline tool-definition mode for new flows. Existing inline tools
are migrated to separate registry entries so their behavior remains unchanged.

### API tools

API tools call your HTTP endpoints during a conversation. Define parameters,
static values, response mappings, async behavior, and filler phrases once, then
reuse the tool in any assistant or flow.

### MCP servers

An MCP tool connects an external server with optional authentication and a
tool allowlist:

* Transport is auto-detected (streamable HTTP or SSE).
* An empty whitelist means *all* tools of that server are allowed.
* Oversized tool results are truncated safely.
* An unreachable MCP server never blocks a call — it is skipped and logged as a call event.

### Built-in tools

Built-ins include call transfer, warm transfer, transfer to another assistant,
SMS, email, business hours, callbacks, DTMF/keypad collection, payment-card
collection, variables, and end call.

Cold and warm transfer targets may be either an E.164 phone number or a
`sip:` URI such as `sip:sales@example.com`. Transfer-to-assistant tools can
choose which conversation messages are passed to the target assistant.

### API and MCP management

* **REST API:** [`GET`/`POST /tools`, `GET`/`PATCH`/`DELETE /tools/{id}`](/api-reference/introduction), `/tools/{id}/usage`, `/tools/{id}/versions`, restore, and revision-protected assistant assignments.
* **MCP:** [`list_tools`, `get_tool`, `get_tool_usage`, `create_tool`, `update_tool`, `delete_tool`, `list_tool_versions`, `restore_tool_version`, `get_assistant_tools`, `set_assistant_tools`](/api/mcp#available-tools).

Tool responses include a monotone revision. Send the expected revision when
updating a tool or replacing assignments to prevent lost concurrent changes.
Version, usage-impact, and restore operations are available through the REST
API and equivalent MCP tools.

`DELETE` archives only unused tools and returns `409 tool_in_use` while a
reference exists. Set `is_active: false` with `PATCH` to stop new invocations
and active-call use immediately without removing assignments.

Secret values never leave the server and are always masked as `•••`. Active
calls adopt valid registry changes at a safe tool boundary. If a reload fails,
the call keeps its last working tool snapshot.

## Webhooks after the call

When a call finishes, the platform pushes the result to you — the standard way to feed CRMs and downstream automation.

### `call.completed`

Sent to two kinds of receivers:

1. **Per-assistant webhook URL** — quick setup, unsigned.
2. **Workspace webhooks** — managed centrally, **signed** with HMAC-SHA256 over the raw body:

```text theme={null}
X-Famulor-Signature: sha256=<hex digest>
```

Verify by computing the HMAC of the raw request body with your webhook secret and comparing digests.

### Payload contents

The payload includes call metadata (assistant, direction, status, duration, timestamps), the **transcript**, collected **flow variables** (from [collect nodes](/flow-builder/nodes#collect)), lead/campaign context for campaign calls, and links to artifacts such as the recording.

When an outbound call fails, `data.failure` contains the same provider-neutral
object returned by `GET /calls/{id}`:

```json theme={null}
{
  "operation": "outbound_call",
  "code": "busy",
  "message": "The destination is busy. Try again later.",
  "retryable": true,
  "action": "retry_later"
}
```

Raw SIP status, connection diagnostics and SDK error strings are internal and
are not included. A resent webhook is rebuilt from the current stored call and
includes the normalized failure for legacy calls as well.

<Tip>
  Respond `2xx` quickly (under a few seconds) and process asynchronously. Non-2xx responses are treated as delivery failures.
</Tip>

## Polling instead of pushing

Everything a webhook delivers can also be fetched via the [REST API](/api-reference/introduction) (`GET /calls`, `GET /calls/{id}`) or the [MCP tools](/api/mcp#available-tools) (`list_calls`, `get_call`) — useful for reconciliation jobs and backfills. `POST /calls` remains asynchronous and returns `queued`; poll or use the webhook for the final `status` and optional `failure`.