> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

> Trigger n8n workflows from your agent. Add a Webhook node in n8n, paste the URL into thinnestAI, and the agent can POST payloads to run the workflow.

# n8n Integration

<Note>
  n8n is configured through the unified **[API & Webhooks](/docs/tools/api-webhooks)** tool in **Webhook** mode. This page covers the n8n-specific setup; see the unified tool page for everything else.
</Note>

Trigger your n8n workflows from an agent conversation. Whether you self-host n8n or use n8n Cloud, the integration works the same way: the agent fires a webhook when something worthy happens, and n8n picks it up to run whatever workflow you've wired.

## How it works

1. In n8n, add a **Webhook** node as the workflow's trigger.
2. Copy its Production URL (looks like `https://n8n.yourhost.com/webhook/abc123` or `https://your-workspace.app.n8n.cloud/webhook/abc`).
3. In thinnestAI, add the **n8n** tool to your agent and paste the URL.
4. When the agent decides to trigger the workflow, it POSTs a JSON payload to that URL.
5. n8n receives the payload and runs downstream nodes (CRM, databases, messaging — anything n8n supports).

No API keys, no OAuth, no per-platform credentials in thinnestAI. The webhook URL is the auth surface; for extra protection n8n's Webhook node supports Header Auth.

## Setting it up

### Step 1 — create the n8n workflow

1. Open n8n (self-hosted or Cloud).
2. Create a new workflow and add a **Webhook** node as the first step.
3. Configure the node:
   * **HTTP Method**: `POST`
   * **Path**: a unique slug (e.g. `thinnest-leads`)
   * **Response Mode**: "Immediately" (so the agent doesn't wait on your whole workflow)
   * *(Optional)* **Authentication**: set to **Header Auth** and add a credential like `X-Webhook-Secret: <your-random-secret>`.
4. Switch to the **Production URL** tab on the node and copy the URL.
5. Wire downstream nodes (HTTP request to your CRM, database insert, Slack message, etc.) and activate the workflow with the top-right toggle.

A deactivated workflow won't run production webhooks even if the URL is correct — activating is a common miss.

### Step 2 — add the tool in thinnestAI

1. Open your agent → **Tools** → **Add Tool** → **API & Webhooks**, and choose **Webhook** mode.
2. Paste the n8n Webhook Production URL.
3. (Optional) If you enabled Header Auth in n8n, paste the secret in the **Header Auth Secret** field. thinnestAI sends it as `X-Webhook-Secret` on every request.
4. Save.

### Step 3 — tell the agent when to use it

Add a line to your agent's instructions:

```
When a caller finishes describing an issue, trigger the n8n workflow
with their contact info and a summary of what they reported.
```

The agent now has two LLM-callable functions:

| Function                                                                                      | When to use                                                                                   |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `send_event(event_name, customer_name, customer_email, customer_phone, notes, custom_fields)` | Structured CRM-style events (new lead, support ticket, callback request). Use for most cases. |
| `send_webhook(data, event_type)`                                                              | Free-form — send any JSON payload. Use for non-CRM data.                                      |

## Payload format

Every request n8n receives has this shape:

```json theme={null}
{
  "event": "support_ticket",
  "source": "thinnestai",
  "data": {
    "customer_name": "Priya Patel",
    "customer_email": "priya@example.com",
    "customer_phone": "+91-98-7654-3210",
    "notes": "Billing question — charged twice for October invoice"
  }
}
```

In n8n, downstream nodes can reference fields with expressions like `{{ $json.body.data.customer_email }}` — the whole payload sits under `$json.body`.

## Example: support ticket → Freshdesk + Slack

**Voice flow:**

```
User: "Hey, you guys charged me twice last month. Invoice #INV-8822."
Agent: "Really sorry about that. I'm raising a priority ticket for finance now.
        What's the best email to reach you on?"
User: "priya@example.com"
Agent: "Got it. You'll hear back within an hour."
       [calls send_event with event_name="billing_issue",
        customer_email="priya@example.com", notes="Duplicate charge Oct invoice INV-8822"]
```

**n8n workflow:**

```
Webhook → Freshdesk: Create Ticket (priority=High) → Slack: Post to #billing
```

## Securing the webhook

### Option 1 — Header Auth (recommended)

1. In the n8n Webhook node, set **Authentication** to **Header Auth**.
2. Click **Create New Credential**, name it, set:
   * Header Name: `X-Webhook-Secret`
   * Header Value: a long random string
3. In the thinnestAI tool config, paste the same random string into **Header Auth Secret**.

n8n rejects requests without the matching header; anyone who discovers the URL alone still can't trigger your workflow.

> **Important:** The n8n tool always sends its secret on the `X-Webhook-Secret` header. If your n8n Header Auth credential uses a different header name (for example `Authorization` or `X-API-Key`), n8n will reject the request because the header won't match.
>
> If you need a custom header name, use the generic **[Webhook](/docs/tools/crm-webhooks#webhook-tools-zapier--makecom--n8n)** tool instead — it accepts a `webhook_headers` field where you can pass any header name you want.

### Option 2 — IP allow-listing (self-hosted only)

If you self-host n8n behind a reverse proxy, you can allow-list thinnestAI's outbound IPs at the proxy level. Ask support for the current IP list if you go this route.

## Self-hosted vs. n8n Cloud

Both work identically with this tool. The only difference is the Webhook Production URL:

| Edition             | URL pattern                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **n8n self-hosted** | `https://n8n.yourdomain.com/webhook/<path>`                                                                                      |
| **n8n Cloud**       | `https://<workspace>.app.n8n.cloud/webhook/<path>`                                                                               |
| **n8n local dev**   | `https://localhost:5678/webhook/<path>` (won't work from thinnestAI Cloud — use a tunnel like ngrok if you need to test locally) |

## Limits & pricing

* **n8n self-hosted**: no per-execution fee; you're limited by your server capacity.
* **n8n Cloud**: varies by plan — check your workspace's execution quota.
* **thinnestAI's side**: no per-call charge. Unlimited webhook triggers from the agent.
* **Latency**: the agent waits up to 15s for n8n to respond. Set the Webhook node's **Response Mode** to "Immediately" so n8n acks quickly and runs downstream nodes async.

## When to use n8n vs. alternatives

| Need                                             | Use                                                                                     |
| ------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Trigger a self-hosted automation workflow        | **n8n** (this tool)                                                                     |
| Trigger Make.com / Integromat                    | Use the [Make.com tool](/docs/tools/make)                                               |
| Generic HTTP POST to your own backend            | Use the [generic Webhook tool](/docs/tools/crm-webhooks#webhook-tool-zapier--make--n8n) |
| Deep native integration (Gmail, HubSpot, Sheets) | Use the native [Gmail](/docs/tools/gmail) / [Sheets](/docs/tools/google-sheets) tools   |

## Troubleshooting

| Symptom                                       | Fix                                                                                                        |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Agent says "Webhook returned status 404"      | Workflow is deactivated in n8n. Activate it with the top-right toggle.                                     |
| Agent says "Could not connect to webhook URL" | URL is wrong, n8n is down, or you used the Test URL instead of the Production URL.                         |
| n8n returns 401 / 403                         | Header Auth mismatch. Re-check that the secret in thinnestAI exactly matches the n8n credential.           |
| Workflow fires but fields empty               | n8n downstream nodes reference the wrong path. Fields live under `$json.body.data.*` (not `$json.*`).      |
| Timeout every time                            | Your workflow runs long and n8n isn't set to Respond Immediately. Change the Webhook node's Response Mode. |

## Configuration reference

| Field                  | Required | Description                                                                              |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------- |
| **n8n Webhook URL**    | Yes      | The Production URL from the Webhook node.                                                |
| **Header Auth Secret** | No       | Matches the n8n Webhook node's Header Auth credential value. Sent as `X-Webhook-Secret`. |

## Next steps

* **[Make.com](/docs/tools/make)** — same pattern but for Make.com scenarios.
* **[CRM & Webhooks](/docs/tools/crm-webhooks)** — generic webhook tool and CRM lookup patterns.
* **[Custom Tools](/docs/tools/custom-tools)** — build bespoke HTTP tool calls when a webhook isn't expressive enough.