n8n integration

This guide walks you through the installation and running of custom Toolhouse nodes in n8n, enabling you to call Toolhouse agents within n8n workflows.

This guide assumes you have the latest versions of Docker and Node.js installed in your environment.

Installation

First, set up a new folder to store your n8n instance.

Run these commands in the terminal:

git clone <https://github.com/toolhouseai/toolhouse-n8n.git>

Change the directory:

cd toolhouse-n8n

Then run:

npm install

Note: Make sure you have Node.js installed and updated to at least v16.

npm run build

After that, make sure you have Docker open on your desktop and run:

docker compose up

A successful run will look like this:

You will now be able to access n8n at http://localhost:5678.

If the run fails, ensure Docker is open and running the correct container.

Your Docker Desktop should look like this:

Using n8n

Your landing page should look like this:

Create Credentials

To use Toolhouse agents in your workflows, you'll need to connect your Toolhouse account.

From the sidebar, select Credentials > Add Credential.

You will need a Toolhouse API key. To get your API key, go to Toolhouse API Keys and either:

• Copy an existing key, or

• Click Generate New Key

Paste your API key into the appropriate field in the n8n node configuration, and then click Save to apply the changes.

You're now ready to use Toolhouse Nodes in your workflows!

Starting a Toolhouse Agent Conversation on Workflow Execution

Here is an example workflow using Custom Toolhouse Nodes.

Add a Trigger Node

Start your workflow with a trigger node. In this example, use the Manual Trigger node, which enables you to launch the workflow by clicking Execute Workflow.

Add the Toolhouse Node

Add the Toolhouse Agent Node to your flow.

You can use this node to:

• Start a new conversation, or

• Continue an existing one by providing the agentId and the previous agentRunId.

This allows your workflow to pick up where a previous interaction left off.

After selecting Start Conversation in the Toolhouse Node, your flow should resemble the following structure:

To choose an agent, open the Toolhouse Node and use the dropdown menu to select the agent you want to use in this workflow.

If no agents are found:

1. Reopen your credentials

2. Confirm your Toolhouse API key is valid

This is where all of your Toolhouse agents will appear.

If you haven’t created any agents yet, please follow our Quickstart Guide to get started quickly and learn how to set up your first agent.

Executing the Flow

When you click “Execute Workflow”, this flow will initiate a conversation with your Toolhouse agent.

Using Webhooks

You can use webhooks to trigger your n8n workflows automatically from Toolhouse agents.

Prerequisite: Make sure you have an active Ngrok account, as it will be used to expose your local n8n instance to the internet.

Once configured, your Toolhouse agent will be able to call this webhook and trigger your n8n automation in real time.

Step 1:

Open your n8n instance in the browser.

Create a new Webhook node in your workflow.

Then, navigate to the Production URL.

You’ll need the Production URL of your webhook — this is the URL that Toolhouse agents will call.

For example:

<http://localhost:5678/webhook/4859e428-d117-4fea-a0f8-8ee94efbf600/toolhouse-call>

Make sure you're using the Production URL (not the Test URL) from the webhook node in n8n.

Next, expose your local n8n instance using Ngrok by running:

ngrok http 5678

This will create a public URL that forwards to your local localhost:5678, allowing Toolhouse agents to trigger your workflows remotely.

This is what your terminal should look like after running Ngrok:

Copy the first Forwarding link (the https one). In this example:

https://4a9fcad2f765.ngrok-free.app

Scheduling your agents

Now you’ll create the callback URL that Toolhouse agents will use.

Take your Production URL from n8n (e.g.):

<http://localhost:5678/webhook/4859e428-d117-4fea-a0f8-8ee94efbf600/toolhouse-callback>

Replace the localhost:5678 portion with your Ngrok forwarding domain.

Example callback URL:

<https://4a9fcad2f765.ngrok-free.app/webhook/4859e428-d117-4fea-a0f8-8ee94efbf600/toolhouse-callback>

Use this full URL when setting up your Toolhouse agent’s webhook.

Using Toolhouse Schedules

Now, you’ll set up schedules that determine when your agents should run. These schedules will remotely call the webhook URL you configured, triggering your n8n workflow at the specified times.

To create a new schedule, follow these steps:

1. Navigate to https://app.toolhouse.ai/schedules.

2. Click New Schedule in the top right corner.

This will open schedule creation, where you can configure how often your agent should run and which webhook it should call.

Next, choose the agent you want to schedule from the dropdown.

Note: If you don’t have any agents yet, you can create one at https://app.toolhouse.ai/agents.

Once you've selected an agent, continue configuring the schedule details.

Then, choose a cadence — this defines how often the agent should run (e.g., every 5 minutes, hourly, daily).

After setting the cadence, enter the Callback URL you created earlier.

This is the public webhook URL exposed by Ngrok, which will trigger your n8n workflow.

Completed Example

Here’s a completed example using this callback URL we generated earlier:

<https://4a9fcad2f765.ngrok-free.app/webhook/4859e428-d117-4fea-a0f8-8ee94efbf600/toolhouse-callback>

Once you've filled out all the fields, click Create Schedule.

Your agent is now scheduled! When the schedule runs, it will call the webhook and trigger your n8n workflow automatically.

Next steps

You're All Set! Your n8n instance is now fully connected to Toolhouse agents.

You can go ahead and build your own workflows with Toolhouse and n8n.

Happy Building!

Need help? Visit Toolhouse Support or ask in our Community Discord.