n8n-toolkit

n8n Toolkit

Overview

n8n is the orchestration layer for GTM when Clay's spreadsheet model or a single MCP agent isn't enough — multi-branch routing, custom APIs, queue pause/resume, and cross-tool pipelines with real error recovery. The mistake: copying a generic "webhook → API → CRM" template without motion-specific logic, idempotency, or human gates before sends.

This skill is the n8n implementation anchor: which flows to build by GTM motion, how to build them node-by-node, and how MCP fits (agents draft/research; n8n executes with guardrails). Load n8n-automation for when to choose n8n vs Clay; load mcp-setup for agent-side MCP config.

When to Use

• "Build an n8n workflow for inbound leads"
• "n8n outbound enrichment pipeline"
• "Connect MCP to n8n" / "n8n orchestrate MCP tools"
• "Signal workflow — funding, job change, hiring"
• "CRM sync between HubSpot and Salesforce"
• "Replace Clay export with n8n for complex routing"
• "n8n reply classification webhook"
• "Event-driven GTM automation"

Use Clay instead (clay-toolkit, clay-loops-toolkit): spreadsheet enrichment, waterfall columns, recurring signal monitors with credit control.

Use MCP agents instead (mcp-setup, leadmagic-mcp): ad-hoc research, drafting, CRM reads — with human confirmation on writes.

Use n8n when: deterministic pipelines, SLA-bound inbound, bulk batch jobs, multi-system sync, or branching that exceeds Clay formulas.

Authoritative Foundations

• n8n. Visual iPaaS with 400+ nodes, self-host or cloud. Queue mode for pause/resume. Sub-workflows for reusable modules. Error Trigger workflows for global failure handling.
• Model Context Protocol (MCP). Standardizes agent tool discovery. n8n sits below agents as execution plane — agents call n8n webhooks to run approved pipelines; n8n does not replace MCP for interactive research.
• iPaaS Integration Patterns. Webhook (real-time), poll/cron (batch), idempotency keys (dedupe), dead-letter queue (failed records), circuit breaker (stop on API outage).
• Winning by Design Bowtie. Inbound flows must hand off Marketing → Sales with SPICED fields; closed-won → CS with health score. n8n enforces field requirements at routing gates.
• ColdIQ Signal-to-Action. One signal → one play. n8n Switch node routes by signal_type; never one generic "signal outreach" branch.

n8n vs Clay vs MCP — Decision Matrix

Need	Tool	Why
Waterfall email enrichment on a list	Clay	Column-native, credit-efficient
Recurring funding/job-change monitor	Clay Loops	Built-in cadence + table UX
Inbound form → enrich → route in <60s	n8n	Webhook SLA, branching
HubSpot ↔ Salesforce bidirectional sync	n8n	Custom field mapping, conflict rules
Reply webhook → classify → CRM task	n8n	Sequencer webhooks + AI node
Agent researches 5 accounts interactively	MCP	Tool calls with human in loop
Agent triggers approved bulk enrich job	MCP → n8n webhook	Agent proposes; n8n executes
Complex if/else across 6+ systems	n8n	Switch, Merge, sub-workflows

Step-by-Step: How to Build a GTM Flow

Phase 1: Flow Selection

Pick blueprint from references/gtm-flow-catalog.md:

Motion	Flow ID	Trigger	Latency Target
Inbound	INB-01 Form → enrich → score → route	Webhook	<60s
Inbound	INB-02 Inbound triage + Slack	Webhook	<30s
Outbound	OUT-01 List upload → batch enrich → CRM	Manual/Cron	2–4h / 5K rows
Outbound	OUT-02 Clay webhook → sequencer	Webhook	<2min
Signal	SIG-01 Funding → enrich → task	Cron daily	Same day
Signal	SIG-02 Job change → champion play	Cron daily	Same day
Lifecycle	LIF-01 Meeting held → nurture branch	CRM webhook	<5min
Lifecycle	LIF-02 Trial signup → onboarding	Webhook	<2min
RevOps	REV-01 CRM hygiene re-verify	Weekly cron	Batch
RevOps	REV-02 Forecast rollup → Slack	Cron	Weekly
Agent	MCP-01 MCP-approved pipeline trigger	Webhook	On demand

Phase 2: Architecture (5-Layer Stack)

Every production flow uses this stack:

TRIGGER → NORMALIZE → ENRICH/SCORE → ROUTE → ACTION + LOG
              ↓              ↓            ↓
         idempotency    rate limit    human gate (if send)

Layer rules:

1. Trigger: Webhook, Cron, CRM trigger, or another workflow. Always capture event_id for dedupe.
2. Normalize: Set node — map to canonical schema (email, domain, company, source, signal_type, icp_tier).
3. Enrich/Score: HTTP Request (LeadMagic, Clay API), Code node (ICP score), or AI node (classify reply). See references/node-patterns.md.
4. Route: Switch on icp_score, signal_type, intent, geo.
5. Action: CRM upsert, sequencer enroll, Slack, task create. Never auto-send cold email without human gate unless pre-approved tier-1 signal play.

Phase 3: Node Implementation

Standard node order — full configs in references/node-patterns.md:

Webhook → Set (normalize) → IF (idempotency check in Redis/Sheet)
  → HTTP Request (enrich) → Code (score) → Switch (route)
    → HubSpot Upsert → Slack → Respond to Webhook

Required on every production workflow:

• Error Trigger workflow (global) → Slack + log row
• Wait node between API calls (100–500ms) for rate limits
• Split In Batches (size 10–50) for bulk
• Credentials in n8n store — never in exported JSON
• Workflow name: [PROD] INB-01 Form Enrich Route

Phase 4: MCP Integration

Three patterns — detail in references/mcp-patterns.md:

Pattern A — Agent triggers n8n (recommended)

Jesse/Claude agent (MCP: CRM read, enrichment lookup)
  → Human approves "run enrichment job"
  → HTTP POST to n8n webhook (MCP-01)
  → n8n executes batch pipeline with audit log

Pattern B — n8n calls external APIs (not MCP directly)

n8n HTTP Request → LeadMagic / HubSpot / Clay API
(MCP is for agents; n8n uses REST natively)

Pattern C — n8n AI Agent node + MCP-style tools

n8n LangChain Agent node with Tool Workflow nodes
  → Sub-workflow per tool (enrich, CRM read, classify)
  → Use for reply classification (LIF-03) with bounded tools

Load mcp-setup for agent-side guardrails. n8n webhook auth: HMAC header or secret query param — never expose unauthenticated production webhooks.

Phase 5: Test and Deploy

1. Test mode: Pin test data; run node-by-node execution
2. Dry run: Set CRM nodes to read-only branch first
3. Canary: Route 5% traffic via Switch before full cutover
4. Activate: Tag [PROD]; enable Error Trigger workflow
5. Monitor: First 24h — Slack on every error + daily execution count

Run scripts/check-output.py on deliverable before handoff.

GTM Flow Quick Reference

Full node lists in references/gtm-flow-catalog.md.

Inbound (INB-01)

Form webhook (HubSpot/Typeform/Cal.com)
  → Normalize fields
  → LeadMagic: verify email
  → IF invalid → Slack #bad-leads + stop
  → LeadMagic: company enrich
  → Code: ICP score (0–100)
  → Switch:
      ≥70 → Create CRM contact + assign round-robin + Slack #hot-leads
      40–69 → Nurture list + marketing tag
      <40 → Archive + reason code
  → Respond 200 (form UX)

Align fields with inbound-triage and SPICED-lite on CRM create.

Outbound (OUT-01)

Cron weekly OR manual webhook (list_id)
  → Google Sheets / Airtable: get rows where status=queued
  → Split In Batches (25)
    → LeadMagic find email → verify
    → IF verified → HubSpot upsert + status=enriched
    → IF not found → status=manual_review
  → On batch complete → Slack summary

Hand off to sequencer via OUT-02 (Clay or n8n webhook to Smartlead).

Signal (SIG-01 Funding)

Cron daily 6am
  → Source: CRM watchlist OR funding API / Clay export webhook
  → Filter: funding in last 7 days + ICP tier 1–2
  → Enrich contacts at account
  → Set signal_type=funding, why_now, source_url
  → CRM: create task for owner + tag signal:funding
  → Slack: #signals with account link

Route copy from funding-signal-play — not generic outreach in n8n.

Reply handling (LIF-03)

Sequencer reply webhook (Instantly/Smartlead/Outreach)
  → AI node OR HTTP to classification API (ai-prompts-toolkit P08)
  → Switch: positive / objection / OOO / unsubscribe / wrong person
  → positive → CRM task + Slack AE
  → unsubscribe → CRM opt-out + suppression list
  → wrong person → referral extract → new contact create

Maps to reply-handling categories exactly.

MCP trigger (MCP-01)

Webhook POST { job_type, params, requested_by, approval_token }
  → IF valid HMAC + approval_token → route job_type
  → enrich_batch | sync_crm | classify_replies
  → Execute sub-workflow
  → Log to Sheet: timestamp, job_type, rows, status
  → Callback URL optional

Sub-Workflow Library

Extract reusable modules:

Sub-workflow	Input	Output
sw-enrich-contact	email or domain	verified_email, company, title
sw-icp-score	company fields	score 0–100, tier
sw-crm-upsert-contact	contact object	crm_id, created/updated
sw-slack-notify	channel, message	ok
sw-idempotency-check	event_id	skip or continue

Call via Execute Workflow node — keeps main flows readable.

Environment and Credentials

# Self-hosted n8n .env — never commit
N8N_ENCRYPTION_KEY=...
LEADMAGIC_API_KEY=lm_xxx
HUBSPOT_ACCESS_TOKEN=pat-xxx
SLACK_WEBHOOK_URL=https://hooks.slack.com/...
N8N_WEBHOOK_HMAC_SECRET=whsec_xxx

Credential types: Header Auth (API keys), OAuth2 (HubSpot/SF), Predefined (Slack). Rotate keys quarterly; re-link credentials after rotation.

Output Format

Deliverable package:

1. Workflow blueprint (templates/workflow-blueprint.md) — flow ID, trigger, node diagram, field schema, routing rules
2. Node configuration — HTTP endpoints, auth, body, response mapping
3. MCP integration note — if agents trigger this flow (Pattern A/C)
4. Error handling — Error Trigger workflow, retry policy, dead-letter
5. Deployment checklist — 8-point pre-activation (see Quality Check)

Quality Check

• Flow ID assigned from catalog (INB/OUT/SIG/LIF/REV/MCP)
• Canonical schema on Normalize step (email, domain, source, event_id)
• Idempotency check before CRM writes
• Rate limiting between API nodes (100–500ms Wait)
• Human gate before any cold outbound send
• Error Trigger workflow linked; failures notify Slack
• Credentials in store — not in export JSON
• Webhook authenticated (HMAC or secret)
• Signal flows map to one play (funding-signal-play, etc.)
• Inbound captures SPICED-lite fields for CRM
• Batch flows use Split In Batches with size ≤50
• Workflow named [PROD] {FLOW-ID} {description}

Common Pitfalls

1. n8n as spreadsheet. Rebuilding Clay waterfalls row-by-row in n8n costs more to maintain. Fix: Clay enriches; n8n routes and syncs.

2. Unauthenticated webhooks. Public URL gets spammed; CRM fills with junk. Fix: HMAC verification node first step.

3. No idempotency. Form double-submit creates duplicate contacts. Fix: event_id or email hash check in Redis/Sheet before create.

4. Agent auto-sends via n8n. Compliance and brand risk. Fix: MCP-01 requires approval_token; sends stay in sequencer with human review.

5. One giant workflow. 40 nodes, unmaintainable. Fix: sub-workflows per enrich, CRM, notify.

6. Silent failures. Error branch empty. Fix: global Error Trigger + row log.

7. Mixed signal routing. One branch for all signals. Fix: Switch on signal_type; load play skill per type.

Execution Artifacts

• references/framework-notes.md — Framework anchors
• templates/output-template.md — Deliverable structure
• scripts/check-output.py — Validates workflow deliverables
• references/gtm-flow-catalog.md — Full flow blueprints by motion
• references/mcp-patterns.md — MCP + n8n integration patterns
• references/node-patterns.md — HTTP, webhook, batch, AI, error nodes
• templates/workflow-blueprint.md — Design doc template

Related Skills

• n8n-automation — When to use n8n vs Clay (decision layer)
• mcp-setup / leadmagic-mcp — Agent-side MCP configuration
• clay-toolkit / clay-loops-toolkit — Enrichment and signal loops
• ai-prompts-toolkit — Prompts for AI nodes (classify, research)
• crm-toolkit / crm-integration — CRM field requirements
• inbound-triage — Inbound scoring rules
• reply-handling — Reply category → action mapping
• proactive-alerts — Slack alert formatting
• event-analytics — Track flow executions as events