Automations with n8n

An agent that can only talk is half a product. Tools let it act: create a ticket, look up an order, send an email, write to your CRM. Vicero connects to n8n so those actions are workflows you can build visually rather than code someone has to maintain.

The integration runs both ways:

Vicero → n8n — the agent calls a workflow as a tool, via the workflow's webhook.
n8n → Vicero — a workflow calls back into Vicero over the REST API to post a message, update a conversation, or read analytics.

Bind a workflow as a tool

A Vicero-callable workflow starts with a Webhook node. For a synchronous tool it ends with a Respond to Webhook node returning JSON. Activate the workflow so its production webhook registers.

Then, in the dashboard: Automations → pick the workflow → Bind as tool → choose the agent and the mode.

Mode	Behaviour
sync	Vicero posts to the webhook and feeds the response JSON straight back to the model in the same turn. Use it when the work takes a second or two.
async	The workflow does long-running work and posts a signed result back when it is finished. Use it for anything that might take longer than a visitor will wait.

Finally, enable Tools on the agent. When the model decides the tool is relevant, it calls it and uses the result in its answer.

If your workflow does not appear in the list, you can bind it directly by pasting its webhook URL.

What Vicero sends

Every outbound tool call is a signed POST to the workflow's webhook:

{
  "args": { },
  "mode": "sync",
  "run_id": "…",
  "conversation_id": "…",
  "callback_url": "… (async only)"
}

Two headers come with it:

X-Vicero-Signature — HMAC-SHA256 of "{timestamp}.{body}"
X-Vicero-Timestamp

Verify the signature in any workflow that does real work. Without it, the webhook URL is the only thing standing between a stranger and your ticketing system. Vicero will refuse to bind a workflow that does not verify, when the operator has enabled that requirement.

Async results

An async workflow posts its result back to POST /v1/tools/n8n/callback:

{ "run_id": "…", "output": { }, "status": "ok" }

signed with the same secret. That resolves the pending tool run.

Calling Vicero from n8n

For the other direction, call the Vicero REST API from an HTTP Request node, using a credential your workspace administrator provides. See API authentication.

Vicero also emits outbound webhooks — message.created, handoff.requested, conversation.closed and others — which an n8n Webhook node can receive to trigger a flow. See Webhooks.

When it does not work

Symptom	Usual cause
Workflows do not appear in Automations	The workspace has no n8n connection configured, or the base URL is wrong. Bind by webhook URL instead.
The tool call returns an error	The workflow is not Active, or a sync workflow has no Respond to Webhook node.
An async callback is rejected	The signature or `run_id` does not match. Sign with the same secret Vicero sends.

Every tool call is logged under the agent's Tools tab with its inputs, output, latency and error — start there, then check the n8n execution log.