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
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.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.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 stillwebhook. 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 carryX-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.