n8n
Build n8n workflows with nodes, webhooks, credentials, and expression-based data mapping through its editor or REST API.
SKILL.mdskills/n8n/SKILL.md
GitHubn8n Workflow Automation AI Skill Guide (Claude)
Overview & Engine Architecture
n8n is a workflow automation platform (self-hosted or n8n Cloud) where workflows are directed graphs of nodes. Data moves as items (JSON arrays). Triggers (Webhook, Schedule, app triggers) start executions; downstream nodes transform and call external systems. Credentials are encrypted at rest; production scale often uses queue mode (Redis + workers + optional webhook processors).
Claude operates as a Principal Automation Architect: webhook ingress hardening, at-least-once idempotency, expression-safe data mapping, error workflows, and API-managed workflow exports.
┌─────────────────────────────────────────────────────────────┐
│ n8n Production Stack │
│ │
│ Ingress │
│ ├── Webhook (Header/Basic/JWT auth, IP allowlist) │
│ ├── Schedule / app triggers │
│ └── Respond to Webhook (sync) vs async queue handoff │
│ │
│ Execution │
│ ├── Item fan-out (1 trigger → N items) │
│ ├── SplitInBatches / rate limits │
│ └── Code / HTTP Request / native app nodes │
│ │
│ Scale-out (optional) │
│ ├── Redis queue + worker processes │
│ ├── Webhook processors + load balancer │
│ └── Shared N8N_ENCRYPTION_KEY across all nodes │
│ │
│ Control plane │
│ ├── REST API /api/v1 + API keys │
│ ├── Workflow JSON in git │
│ └── Credentials vault (never in exported JSON secrets) │
└─────────────────────────────────────────────────────────────┘
When to use / when not to
Use when
- Integrating SaaS APIs with visual branching, retries, and ops-friendly execution logs.
- Self-hosting automations where data residency or custom nodes matter.
- Webhook-driven pipelines that need quick iteration before a dedicated worker service.
Do not use when
- You need exactly-once side effects without your own idempotency store (n8n + upstream retries = at-least-once).
- Sub-100ms synchronous webhook SLAs with heavy transforms (prefer ack-fast + async worker).
- HIPAA/PCI scope without reviewing n8n deployment, logging, and credential access patterns.
Operational Capabilities & Agent Directives
- Assume at-least-once delivery: Stripe, Shopify, and custom clients retry on non-2xx or timeouts. Deduplicate before CRM charges, emails, or ledger writes.
- Credential hygiene: Use n8n Credentials or env vars; never commit tokens in Code node source or workflow JSON. Rotate after exports leak.
- Webhook auth by default: Header auth, Basic, or JWT on production URLs; IP allowlist when provider publishes egress IPs.
- Item semantics: One input item can become many; use SplitInBatches for API rate limits; pin sample data when debugging
$jsonpaths. - Queue mode parity: Share
N8N_ENCRYPTION_KEYon main, workers, and webhook processors or credentials decrypt fails on workers. - Fast ack pattern: Respond 202/200 immediately after idempotency reservation; run heavy steps in a child workflow or queue drain.
- Error visibility: Wire Error Trigger workflows or node error outputs; silent failures are common when Zaps/workflows are inactive.
Production patterns
Idempotent webhook chain (conceptual)
Webhook (POST, Header auth)
→ Set (normalize event_id from body.headers)
→ HTTP Request OR Redis/Postgres "claim" idempotency key (INSERT … ON CONFLICT / SET NX)
→ IF duplicate → Respond 200 "already processed"
→ ELSE side effects (CRM, email)
→ Respond to Webhook 200
Code node (normalize + validate):
const items = $input.all().map((item) => {
const j = item.json.body ?? item.json;
const eventId = String(j.id ?? j.event_id ?? "").trim();
if (!eventId) return null;
return {
json: {
eventId,
tenantId: j.tenant_id ?? "default",
payload: j,
receivedAt: new Date().toISOString(),
},
};
}).filter(Boolean);
return items;
Management API (CI activate)
curl -X POST "https://n8n.example.com/api/v1/workflows/42/activate" \
-H "X-N8N-API-KEY: $N8N_API_KEY"
Technical Troubleshooting Matrix
| Issue & signature | Root cause | Fix |
|---|---|---|
| Webhook 404 | Workflow inactive or wrong path/method | Activate; confirm Production URL vs Test URL |
| 401/403 on webhook | Auth header/IP allowlist | Match credential; update allowlist |
| Duplicate CRM rows | Provider retries; no idempotency | Claim event_id before create; upsert by external ID |
Expression undefined |
Wrong path ($json vs $node) |
Pin data; inspect item JSON mid-run |
| Credential works in UI, fails on worker | Missing shared encryption key in queue mode | Align N8N_ENCRYPTION_KEY on all processes |
| Slow webhook response | Heavy sync chain | Ack early; async sub-workflow |
| HTML webhook response broken | n8n 1.103+ sandbox iframe | Use absolute URLs; embed short-lived token in HTML |
Best Practices
- Version workflow JSON in git; document required credential types in README.
- Prefix idempotency keys:
{tenantId}:evt:{stableId}with TTL (24–72h typical). - Prefer native nodes over Code when maintainability matters; Code for small transforms only.
- In queue mode, consider
endpoints.disableProductionWebhooksOnMainProcess+ dedicated webhook processors behind LB. - Log execution ID + external event ID; never log full PII payloads in production retention.
Essential paths
- UI: Workflows / Credentials / Executions
- API:
/api/v1 - Env:
N8N_ENCRYPTION_KEY,EXECUTIONS_MODE=queue, Redis URL
Limitations
- No built-in exactly-once semantics for external side effects.
- Binary/large payloads need explicit handling; relay offload requires n8n ≥ 2.34 on all mains.
- Complex multi-tenant RBAC is DIY (lookup tables + scoped credentials).
Related skills
@zapier— SaaS-first alternative when self-hosting is unnecessary@stripe— signed webhooks + idempotency patterns upstream of n8n@nodejs— custom webhook receivers when n8n is bypassed
Agent Operational Directive
MANDATORY: Treat all webhook triggers as at-least-once. Persist an idempotency key before irreversible side effects. Store secrets in Credentials/env only. Enable webhook authentication on production URLs. Never disable error alerting to “reduce noise.”
Sources
- n8n docs: Queue mode, Webhook node
- Community: r/n8n webhook retries / idempotency
- Patterns: production webhook hardening (signature verify, Redis SET NX)