n8n

n8n-nodes-truetask is the Truetask community node for n8n. It ships two nodes: a trigger that starts an n8n workflow when something happens in Truetask, and an action node that does things in Truetask from one.

Both work against Truetask Cloud and against a self-hosted instance. A self-hosted n8n sitting next to a self-hosted Truetask needs no public internet at all.

Install

On a self-hosted n8n, go to Settings > Community nodes > Install, enter n8n-nodes-truetask and confirm.

To install it by hand, run this in your n8n user folder (usually ~/.n8n) and restart n8n:

cd ~/.n8n/nodes
npm install n8n-nodes-truetask

Credentials

Create a Truetask API credential with two values:

Field	Value
Server URL	Your workspace address, for example https://truetask.example.com, with no path
API token	A personal access token from the App menu > Tokens

Give the token the Can edit (read & write) permission so the action node can change things and the trigger can register its subscription. n8n tests the credential against GET /v1/users/me, so a green check means both the URL and the token are right.

Every workflow acts as the person who owns the token. It sees their boards and nothing else. See REST API for how tokens work.

Truetask Trigger

Pick the Events you care about and, optionally, the Boards. A member must pick at least one board they belong to. A workspace owner or admin can leave Boards empty to listen to the whole workspace.

Activating the workflow registers an outgoing webhook subscription in Truetask, which appears under App menu > Webhooks on the Outgoing tab as n8n: <workflow name>. Deactivating the workflow removes it. Truetask pushes each event, so nothing is polled, and the node verifies the HMAC signature on every delivery before it reaches your workflow.

Each event arrives as one item in the delivery envelope:

{
  "id": "5g2k9h1m3n8p7q4r-w1e2r3t4y5u6i7o8",
  "event": "card.completed",
  "timestamp": "2026-09-10T16:20:22.801Z",
  "data": { "key": "DEVE-538", "title": "n8n community node", "completed": true }
}

data carries much more than that: the task key and link, board and list names, member and tag names, priority, dates and a description excerpt. id is unique per delivery and identical on every retry, so a deduplication step can key on it. See Webhook events for the full field list per event.

Agent events

The trigger offers the agent lifecycle events too, which is what you need to watch work that runs outside Truetask:

Event	When it fires
Agent Run Kicked Off	A kickoff was delivered to an agent
Agent Kickoff Expired	Nothing picked a kickoff up before it expired
Agent Run Handed Off	A workflow step became another agent's turn
Agent Run Needs Input	A run is waiting for an answer
Task Question Asked, Task Question Answered	A blocking question was asked, then answered or dismissed
Agent Run Blocked, Agent Run Stalled	A run is blocked, or went quiet and was flagged
Task Done Proposed	An agent proposed a task as done
Agent Run Approved, Agent Run Returned	A person approved the proposal, or returned it with feedback
Agent Run Completed, Failed, Cancelled	The run ended

See Runners and auto-start for the other end of that loop.

Testing

Click Listen for test event and the node asks Truetask to send the newest matching item right away: a real task, comment or timer in the live shape. You can map fields without waiting for something to happen. If the workspace has nothing of that kind yet, the node simply keeps listening for a live event.

Truetask node

Resource	Operations
Task	Create, Update, Move, Complete, Get, Search
Comment	Add
Note	Create
Timer	Start, Stop
Agent	Kick off
Workflow	Trigger

The dropdowns load from your workspace: boards first, then the lists, members, tags and priorities of the board you chose, the agents and agent workflows of a task's board, and the incoming endpoints a board may use. Every dropdown also accepts an expression with an id.

Tasks are addressed by id

Operations on an existing task take its record id, the id field from a trigger item or a search result, not the human key like DEVE-538.

Workflow > Trigger

This starts the Truetask automations subscribed to an incoming endpoint. The JSON body reaches them as {webhook.body.*} placeholders. The call is made as you, so the endpoint's external credential is not needed.

Agent > Kick off

This starts an AI agent that is a member of the task's board, with the board's default agent workflow or one you pick. The kickoff is delivered straight away when the agent is reachable, and queued with retries otherwise.

Under Options:

• Powers narrows how the kickoff may be delivered: Auto-Start (the agent's own runner, called at its wake URL), Local Access (the Truetask Desktop app of the agent's owner) or Truetask AI (a workspace AI turn as the agent). Leave it empty for any power the agent has, or pick only Auto-Start to send the work to an external runner.
• Model and Effort are hints for an agent running on its owner's desktop. A runner behind a wake URL picks its own. Max effort is Claude Code only and Minimal is Codex only.

See Delegating work and Creating an agent.

Using it with an AI agent

The Truetask node can be used as a tool by n8n's AI Agent node, so an agent in n8n can create tasks and comments as part of its reasoning.

For a broader surface, n8n's MCP Client Tool node talks to the Truetask MCP server without this package: point it at <workspace>/mcp with a personal access token as a Bearer header. The community node is the better fit for deterministic workflows, and MCP is the better fit for an agent that decides what to do. See MCP: connect any AI tool.

Example workflows

The package ships four importable workflows in its examples/ folder, added through Workflows > Import from file:

1. An n8n Webhook node turns any POST into a task on a board.
2. A Truetask Trigger on task completed posts to Slack with the task key and link.
3. An n8n Form creates a task and kicks off an agent on it.
4. A kickoff with Powers set to Auto-Start only, with a trigger on Agent Run Kicked Off and Task Done Proposed posting both to Slack.

Open each one, pick your credential, and fill in the board and, where the example needs it, the task and the agent.

Reachability

The trigger node only works if Truetask can reach your n8n at its webhook URL (WEBHOOK_URL in n8n). For a self-hosted n8n behind a firewall, keep Truetask on the same network or expose the n8n webhook endpoint to it. The action node is the easy direction: it only needs n8n to reach Truetask.

Self-hosted only

If Truetask and n8n sit on the same private network, allow private targets in Settings > General > Network so the subscription can be saved and delivered. See Network.

Related

• Webhooks
• REST API
• Webhook events
• MCP: connect any AI tool