n8n

n8n is a workflow tool. CommSync connects to it in two directions:

• n8n calls CommSync. The n8n MCP Client node calls a tool on the CommSync MCP server. It signs in with OAuth or uses a CommSync API key.
• CommSync starts n8n. When a message arrives, a CommSync webhook posts a signed event to an n8n Webhook node.

A tool can list threads, read a conversation, add a to-do, or send a text. An n8n workflow checks the signature of each event before it acts.

Most workflows use both directions. CommSync tells n8n that a text arrived, and n8n calls CommSync back to act on it.

Before you start

• You need an n8n instance, in n8n Cloud or self-hosted.
• To receive webhook events, n8n must have a public HTTPS address. CommSync does not post to a private, loopback, or local address.
• Your plan sets the number of webhook endpoints: 1 on Starter, 3 on Pro, and 10 on Power.
• API keys have no plan limit.

Call CommSync from n8n

n8n can reach CommSync in two ways. Both give the same tools.

• OAuth. You sign in to CommSync from n8n, and you choose the lines on the CommSync consent screen. You copy no secret.
• API key. You paste a csk_… key into an n8n credential. Use it when nobody can sign in in a browser, for example on a shared server.

Sign in with OAuth

The consent screen shows where CommSync sends you back. For n8n Cloud, that is your workspace address, for example acme.app.n8n.cloud, and the screen shows the n8n mark. For a self-hosted n8n, the screen shows your own address and a plain tile. CommSync can prove neither the person who owns the workspace nor your own server, so the screen always tells you to check the address. You manage the connection in Settings → Connect AI apps.

Use an API key

Call a tool

Open the Tool list on the node. n8n reads the tool list from CommSync. Choose a tool, for example list_threads. Set Input Mode to JSON, and enter the tool input, for example { "limit": 3 }. Then click Execute step.

The node returns the tool result as JSON. For list_threads, each thread has its line, its contact, its unread count, and a preview of the latest message. The MCP page lists every tool and its input.

Give the tools to an n8n AI Agent

The n8n AI Agent node can also use CommSync. Attach an MCP Client Tool node to the agent. It takes the same URL and the same credential. The agent then picks the CommSync tools that it needs for each request.

Set Tools to Include to Selected, and choose only the tools that the agent needs. With All, n8n sends the description of every CommSync tool (more than 200) to the model on each turn. That makes each turn slower and more expensive, and the model can pick the wrong tool.

Start a workflow from a CommSync event

The Inbound text to to-do template runs when a text or an email arrives. It checks the CommSync signature, answers CommSync, and adds a to-do to Home for the conversation.

How the signature check works

CommSync signs each delivery with your endpoint secret. The X-CommSync-Signature header has the form t=<unix seconds>,v1=<hex>. The v1 value is the HMAC-SHA256 of <t>.<body>. The webhooks page gives the full rule.

Node	What it does
CommSync event	Receives the POST. It waits for the workflow to answer.
Prepare check	Reads t from the header. It builds the string <t>.<body>.
HMAC-SHA256	Signs that string with your signing secret.
Signature valid?	Passes when one v1= value in the header is the same as the result, and t is less than 5 minutes old.
Accept or Reject	Answers 200 or 401.
Inbound message?	Passes only a message.received event for an inbound message.
Create to-do	Calls the create_todo tool. The title is "Reply to" and the contact name, else the sender's number or address, cut to 500 characters. The details hold the message text, cut to 4,000 characters. These are the limits of the tool. Both fields drop NUL characters, which the tool refuses.

Prepare check rebuilds the body with JSON.stringify($json.body). The webhooks page tells you to sign the raw bytes, and this template is a deliberate exception. The n8n Webhook node gives the raw body only as a binary file, and a no-code workflow cannot read it easily. The rebuild is safe because CommSync sends compact JSON from JSON.stringify, and a parse and a new JSON.stringify give the same bytes back. Do not put a node that changes the body before the check. If every event starts to get 401 after a CommSync change, sign the raw body instead.

Prepare check reads t from its own t= part of the header, so the order of the parts does not matter.

During the 24 hours after you rotate a secret, the header has two v1= values. The check passes with either secret. After you rotate, change the secret in the n8n credential.

A retry carries the same event id (evt_…). If your workflow does something that must happen once, keep the event ids that you handled and skip a repeat. The template adds no second to-do, because a to-do title is unique on one conversation. On a repeat, the Create to-do node stops with "a to-do with this title already exists on that conversation". The n8n execution list then shows a failed run.

The same thing happens when the contact writes again while the first to-do is still open. Mark the to-do done, and the next message adds a new one.

When something does not work

What you see	What to check
n8n answers 401 to every event	The signing secret in the Crypto credential is not the secret of this endpoint, or the n8n server clock is more than 5 minutes off.
CommSync refuses the endpoint URL	The URL is private or not HTTPS. Use the public Production URL of n8n.
The MCP Client node fails with 401	Someone revoked the API key or disconnected the app, or the token in the credential is wrong. With OAuth, click Connect on the credential again.
The Connect button does nothing	The browser blocked the sign-in window. Let pop-ups for your n8n address.
A tool says the thread does not exist	The credential cannot see that line. Check the lines of the key in Settings → API Keys, or of the app in Settings → Connect AI apps.
No event arrives	The workflow is not active, or the endpoint does not subscribe to the event. Open the endpoint's delivery log in Settings → Webhooks.
An edit has no effect	n8n runs the published version. Publish the workflow again.

Related