Introduction

n8n is a powerful open-source workflow automation tool that lets you connect apps, APIs, and data without writing extensive integration code. This tutorial covers the fundamentals for beginners: how to set up n8n, create a simple webhook-to-API workflow, transform incoming data, and add basic error handling and scheduling. By the end you’ll have a working automation and best practices to expand from.

What you’ll learn

• Quick n8n setup options (cloud or self-hosted)
• Understanding nodes and the n8n UI
• Building a webhook-triggered workflow that calls an external API
• Transforming data with Set and Function nodes
• Basic error handling and testing strategies

Prerequisites

• A computer with internet access
• An n8n instance (cloud or local). For local testing you can use n8n desktop or Docker.
• Basic familiarity with APIs and JSON is helpful but not required

Step 1 — Set up n8n

You have two common options:

• n8n Cloud: easiest; create an account at n8n.io and follow the onboarding
• Self-hosted (Docker): good for full control. Example quick start with Docker Compose:

yaml
version: '3.1'
services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - 5678:5678
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=changeme

Start with `docker-compose up -d` and visit `http://localhost:5678`.

Step 2 — Get familiar with the UI

• Left column: Node library and workflow canvas
• Middle: Canvas where you place nodes and connect them
• Right column: Node settings and credentials

Nodes are the building blocks: trigger nodes (Webhook, Cron), action nodes (HTTP Request, Email), and utility nodes (Set, Function, Merge).

Step 3 — Build your first workflow (Webhook → Transform → HTTP Request → Response)

We’ll create a workflow that accepts a POST webhook payload, adds a derived field, sends the data to a public API (JSONPlaceholder for demo), and returns a success response.

1. Create a new workflow and rename it “Webhook demo”.
2. Add the `Webhook` node:
– Resource: Webhook
– HTTP Method: POST
– Path: demo-webhook
– Save it.

3. Add a `Set` node to normalize input fields. Connect Webhook → Set.
– In `Set`, add keys matching your expected input, e.g. `firstName`, `lastName`, `email`.
– Optionally add a new field `receivedAt` and set the value to `={{ new Date().toISOString() }}`.

4. Add a `Function` node to create a combined `fullName` field (optional advanced step):

javascript
// Function node code
return items.map(item => {
  const json = item.json;
  json.fullName = `${json.firstName || ''} ${json.lastName || ''}`.trim();
  return { json };
});

Connect Set → Function.

5. Add an `HTTP Request` node to send the data to an external API (JSONPlaceholder used for demo):
– Method: POST
– URL: https://jsonplaceholder.typicode.com/posts
– Body Content Type: JSON
– Body Parameters: select `Send Input Data` so the node sends the incoming JSON

Connect Function → HTTP Request.

6. Add a final `Respond to Webhook` (or Set a custom response) to return a friendly message to the original caller.

7. Activate the workflow or use the “Execute Workflow” to test. Send a POST request to the webhook URL provided by n8n (shown in the Webhook node) with a JSON payload:

bash
curl -X POST 'https://your-n8n-instance/webhook/demo-webhook' \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Sam","lastName":"Green","email":"sam@example.com"}'

If everything is correct, the workflow will execute and you should see the request sent to JSONPlaceholder and the response returned to your curl command.

Step 4 — Testing and debugging

• Use the `Execute Workflow` button in n8n to run and inspect node input/output.
• Check the Execution log for errors and inspect node outputs to verify transformations.
• Use `Set` nodes to inject sample data during testing.

Step 5 — Basic error handling

• Add a `NoOp / Set` node after risky nodes to capture error information.
• Use the `Error Workflow` feature: n8n supports a dedicated error workflow that triggers when your main workflow fails.
• Example approach: after `HTTP Request`, add a conditional `IF` node that checks HTTP status code and routes to a notification (Email/Slack) if the request failed.

Best practices for beginners

• Start small: create simple workflows and iterate.
• Name nodes clearly and add descriptions.
• Use credentials for external services (store them in n8n credentials, not inline).
• Keep transformations centralized with `Set` and `Function` nodes.
• Use version control: export your workflow JSON and store it in a repo.
• Protect production endpoints: use authentication on webhooks and enable basic auth on n8n if self-hosting.

Useful Node Examples

• Webhook: receive real-time events
• Cron: run scheduled automations
• HTTP Request: call REST APIs
• Set: add/remove fields without code
• Function: run small JS transforms (use sparingly)

When to use Function nodes vs Set nodes

• Use `Set` when you need to add or map simple fields (no code).
• Use `Function` for complex logic, loops, or custom JS transformations.

Example Function node to normalize an array of items:

javascript
return items.map(item => {
  const { data } = item.json;
  // normalize and return
  return { json: { normalized: data.map(d => d.trim().toLowerCase()) } };
});

Conclusion and next steps

You now know the fundamentals: setting up n8n, building your first webhook-to-API workflow, transforming data, and adding basic error handling. Next steps:

• Explore more integrations (databases, CRMs, email providers)
• Learn to use credentials and environment variables securely
• Build scheduled automations using the Cron node
• Read n8n community recipes and import example workflows

Happy automating! Try creating a small real-world workflow (e.g., new leads → CRM → welcome email) and iterate from there.