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

# Webhooks vs. agent tools

> Two things share the word «webhook» in Ryvo and they are opposites. Here is which one you need.

Ryvo uses the word *webhook* in two places, and they do almost opposite things.
If you are wiring Ryvo to your systems, this page tells you which one to reach
for before you build the wrong receiver.

## The one-line version

**A tool is a question. A webhook is an announcement.**

A tool is something the agent asks your API **in the middle of a conversation**,
and it waits for your answer to keep talking. A webhook is Ryvo telling you
**something that already happened**, after the fact, with nobody waiting.

## Side by side

|                      | Agent tool                                        | Outbound webhook                         |
| -------------------- | ------------------------------------------------- | ---------------------------------------- |
| Who starts it        | The agent, mid-conversation                       | Ryvo, after the fact                     |
| What it expects back | Your data. The model reads it and uses it         | A `2xx`. Nobody reads the body           |
| Timing               | Synchronous. The caller is on the line waiting    | Asynchronous. Outside the request        |
| If it is slow        | The agent goes quiet. Keep it under a few seconds | Nothing happens. We wait                 |
| Signature            | **None**                                          | `X-Ryvo-Signature`, HMAC-SHA-256         |
| Retries              | Inline, right away. `4xx` is not retried          | Queued, with backoff over hours          |
| Where you set it up  | Agent builder → Tools                             | Settings → Webhooks                      |
| Auth toward you      | The headers you define (bearer, API key…)         | Our signature proves the request is ours |

## Which one do I want?

**You want a tool** when the agent needs to know something to do its job:
check a balance, look up an order, confirm availability, create a ticket while
the customer is still on the line. If the answer changes what the agent says
next, it is a tool.

**You want a webhook** when your system needs to react to something Ryvo
already did: log the conversation, update the deal, kick off a follow-up,
push the transcript into your warehouse. If nobody is waiting on the answer,
it is a webhook.

<Note>
  They are not exclusive, and most setups use both. A sales agent might call
  your CRM **as a tool** to fetch the customer's plan mid-call, and receive a
  `conversation.ended` **webhook** afterwards to log the outcome.
</Note>

## Why the naming is confusing, honestly

In the agent builder, the tool type that points at your API is called
**API request**, but under the hood its stored type is still `webhook`. That is
a historical name we are correcting. If you ever see it in an export or an API
response, it is a tool: the agent calls it, it is not a notification.

## Two mistakes worth avoiding

**Do not verify a signature on a tool call.** Tool calls do not carry
`X-Ryvo-Signature` today. If your endpoint rejects unsigned requests, the
agent's call fails and the conversation stalls. Use a bearer token or an API
key header on the tool instead, which you configure with the tool itself.

**Do not do slow work inside a tool.** The agent is waiting and so is the
person on the call. If the work takes more than a couple of seconds, have the
tool return immediately and do the rest when the `conversation.ended` webhook
arrives.

## Where to go next

* [Webhook overview](/webhooks/overview) and [signature verification](/webhooks/signature-verification).
* [Agent tools](/guides/agents/tools).