Credentials, the integration catalog, the HTTP Request node, webhooks, and community nodes.
A Signal Through field guide. Independent, plain-English documentation; not affiliated with or endorsed by n8n GmbH. Approximately 23158 words.
In this volume:
Every useful workflow eventually has to talk to another system — a mailbox, a spreadsheet, a CRM (the software that tracks your customers and deals), a payment processor. And every one of those systems will ask the same question before it does anything for you: who are you, and are you allowed to do that? Credentials are how you answer. In n8n, a credential is a saved, encrypted bundle of secrets — keys, passwords, tokens — that nodes use to prove your identity to outside services. You create a credential once, attach it to as many nodes as need it, and n8n handles the proving on every execution.
This chapter builds your understanding from nothing: what the common authentication styles actually are and why they exist, how to create and test each one in n8n, how n8n protects them at rest, and the habits that keep a growing credential collection from becoming a liability. Team sharing, role-based access, and external secrets vaults are covered in Chapter 34 (Access, Security, and Secrets for Teams); keeping separate credentials for development and production environments is covered in Chapter 35 (The Platform Surface: API, CLI, Source Control, and Embed).
Two words get used almost interchangeably in this territory, and separating them makes everything else clearer.
Authentication is proving who you are. When you type a password, you are authenticating. Authorization is what you are allowed to do once your identity is established. A service might authenticate you successfully and still refuse to delete a record because your account lacks that permission. When an API call fails, the error code usually tells you which of the two went wrong: a 401 status means "I don't know who you are" (authentication failed), while a 403 means "I know who you are, and no" (authorization failed). Keep that pair in your head — it will save you hours of debugging later, and Chapter 39 (The Troubleshooting Encyclopedia) leans on it heavily.
Why can't you just use your username and password everywhere? Because automation changed the risk model. A password in a workflow would sit in configuration forever, grant total access to your account, and be impossible to revoke without locking yourself out too. The industry's answer was a family of machine credentials: secrets designed to be issued to software, scoped to specific abilities, and revocable without touching your human login. Each of the styles below is a different point on that evolution.
An API key is the simplest machine credential: a long random string the service generates for you, usually from a developer or settings page inside your account. You copy it once, store it somewhere safe, and include it with every request. The service looks it up, sees which account it belongs to, and proceeds.
Think of it as a hotel keycard rather than a passport. It opens doors, it can be cancelled instantly at the front desk, and losing it does not mean losing your identity — but anyone holding it can open the same doors you can, no questions asked. That is the crucial property of API keys: possession is proof. There is no second factor, no confirmation prompt. This is why every provider tells you to treat keys like passwords, and why n8n encrypts them rather than storing them as plain text.
Most services show a key exactly once at creation and never again. If you lose it, you revoke it and generate a new one — a mild annoyance that is actually a feature: show-once means the provider stores only a scrambled fingerprint of your key rather than the key itself, so a database leak on their side does not expose usable keys.
Basic authentication (usually just "basic auth") is the oldest scheme still in wide use: a username and password sent with every request, lightly encoded (Base64, a reversible text packaging — encoding, not encryption) inside a standard header. It survives because it is simple and universally supported. You will meet it on internal tools, older APIs, self-hosted services, and admin endpoints (an endpoint being simply a specific URL an API answers requests on). Because the password travels with every single request, basic auth is only acceptable over an encrypted HTTPS connection — over plain HTTP it is functionally broadcasting your password.
A bearer token is a string sent in a request header
that reads, in effect, "the bearer of this token is authorized." The
name is honest: like a bearer bond, whoever holds it can use it.
Structurally it travels in an Authorization header with the
word Bearer in front of the token itself. Bearer tokens are
how most modern APIs consume credentials — and notably, the tokens that
OAuth2 (next section) produces are delivered as bearer tokens.
Header auth is the generic cousin: some APIs want
their key in a custom header with a name they invented —
X-API-Key is a common convention — rather than the standard
Authorization header. Mechanically it is identical: a name,
a secret value, sent with every request. When a provider's documentation
says "pass your key in the X-Api-Token header," header auth
is what they are describing.
OAuth2 is the scheme behind every "Sign in with Google" and "Allow this app to access your account" screen you have ever clicked through. It exists to solve one specific problem: how do you let an application act on your account without ever giving it your password?
Here is the choreography in plain terms, because once you see it, the mysterious redirects stop being mysterious:
Two vocabulary items complete the picture. The client ID and
client secret identify the application itself to the
service — they say "this request comes from n8n" the way your token says
"on behalf of this user." And scopes are the named
permissions on the consent screen: strings like
calendar.readonly or mail.send that define the
token's exact boundaries. A token scoped to reading calendars simply
cannot send email; the service refuses at the door. Scopes are the
mechanism that makes least privilege — a habit we will return to —
enforceable rather than aspirational.
The payoff for all this ceremony: your password never leaves the service that owns it, permissions are explicit and limited, and you can revoke one application's access from your account's security settings without changing your password or affecting anything else.
| Style | What it is | Where the secret travels | Typical fit |
|---|---|---|---|
| API key | Single random string issued by the service | Header, query parameter, or body, per the API's rules | Developer-oriented APIs, single-account access |
| Basic auth | Username + password, encoded per request | Authorization header |
Older APIs, internal and self-hosted tools |
| Bearer token | "Whoever holds this is authorized" string | Authorization header with Bearer
prefix |
Modern APIs; the delivery format for OAuth2 tokens |
| Header auth | Secret in a custom-named header | Whatever header the API specifies | APIs with their own header conventions |
| OAuth2 | Delegated access via redirect, consent, and tokens | Access token as a bearer token; refresh handled behind the scenes | Big platforms (Google, Microsoft, Slack, and peers), anything user-consent based |
Tip: You rarely get to choose the style — the service dictates it. The skill worth building is recognition: read a provider's API documentation and identify which pattern they are describing, because that tells you exactly which n8n credential type to reach for.
Credentials in n8n are first-class objects, stored separately from
workflows. Delete a workflow and its credentials survive; update a
credential and every workflow using it picks up the change on its next
execution. You can see your collection in the Credentials
tab of the main overview screen (alongside Workflows and
Executions), and on instances with projects enabled, each
project keeps its own credentials list.
There are two roads to creating one, and the second is the one you will actually use most:
From the credentials list: open
Credentials, choose the option to add a new credential, and
search for the service or credential type by name. n8n presents a form
with the fields that type needs.
From inside a node: when you add a node that needs authentication — say, a Slack node — its settings panel shows a credential selector. If you have a matching credential, pick it; if not, choose the option to create a new one and the same form opens in place. This road is better in practice because you cannot pick the wrong credential type: the node already knows what it needs.
What the form asks for depends on the style the service uses, and it maps directly onto the plain-English tour above.
Key-style credentials (API keys, tokens, basic auth) are the simple case: paste the secret into the field, save, done. The only work happens on the service's side — finding where it issues keys, which is usually a developer settings or API section of your account. Chapter 12 (Navigating and Operating the Integration Catalog) covers how each integration's documentation points you to the right place.
OAuth2 credentials for major services are, on n8n
Cloud, often nearly effortless: for many popular services n8n
pre-registers its own application with the provider, so the form may
just show a Connect my account button. Click it, and the
full redirect-consent dance from the previous section plays out in a
popup — you log in on the provider's real site, approve the scopes, and
the popup closes with n8n holding the tokens. Everything in steps 1
through 5 happened; you just did not have to build any of it.
OAuth2 credentials the manual way — required on most
self-hosted instances, and on Cloud for services without a
pre-registered app — ask you to create the application half yourself. In
the provider's developer console you register a new application, and the
provider issues you a client ID and client secret. The n8n credential
form displays an OAuth redirect URL; copy it into the
provider's application settings as the authorized callback URL. Paste
the client ID and secret back into n8n, set any required scopes, then
click Connect my account. It is a one-time setup ritual per
service, and the most common failure is a mismatch in the redirect URL —
the provider rejects the dance if the URL n8n sends does not exactly
match the one you registered, down to the trailing slash.
Watch out: On a self-hosted instance, the redirect URL n8n displays is built from the instance's configured public address. If your instance thinks it lives at
localhostwhile the world reaches it through a domain name, OAuth consent screens will bounce to a dead address and the connection will fail. Chapter 32 (Self-Hosting from Zero) covers setting the public URL correctly — do that before attempting OAuth on a self-hosted box.
For many built-in credential types, n8n verifies the credential when you save it — it makes a harmless real call to the service and reports success or failure right in the credential window. A green confirmation means the secret is valid and the service is reachable. A red failure at this stage is a gift: the problem is in the credential, full stop, and you can fix it before it hides inside a workflow.
Not every credential type supports this pre-flight test — generic types in particular (below) cannot be tested in the abstract, because n8n has no idea what a "valid" call to an arbitrary API looks like. For those, the test is empirical: attach the credential to a node, execute that single node against a cheap, read-only endpoint (most APIs have a "who am I" or account-info endpoint that is perfect for this), and read the result. Chapter 10 (Test, Fix, Activate, and Keep It Tidy) covers single-node execution mechanics.
Tip: When a credential test fails, resist the urge to immediately regenerate keys. First check the boring causes in order: leading or trailing whitespace from the copy-paste, the wrong environment's key (test key against the live API or vice versa), and an account whose API access requires a plan feature you don't have. Whitespace alone accounts for a comic share of first-credential failures.
When you save a credential, n8n does not write your secrets to its database as readable text. They are encrypted with a symmetric cipher — the same key encrypts and decrypts — using an encryption key that belongs to your instance. At execution time, n8n decrypts the credential in memory, injects the secret into the outgoing request, and moves on. Anyone who obtains a copy of the database alone holds ciphertext — the scrambled, unreadable form — and nothing more.
Where that key lives depends on how you run n8n:
On n8n Cloud, the encryption key is managed for you. There is nothing to configure and nothing to lose. This is one of the genuine conveniences of the hosted product (see Chapter 31, Operating n8n Cloud Like an Owner).
On a self-hosted instance, the key is generated
automatically the first time n8n starts and stored in a config file in
n8n's data directory, or you can supply your own via the
N8N_ENCRYPTION_KEY environment variable — the better
practice, because it makes the key explicit and portable. Two
consequences follow, and both matter enormously:
First, back the key up. The database and the key are a matched pair. If your server dies and you restore the database to a new machine without the original key, every credential decrypts to garbage — permanently. There is no recovery path; you would recreate every credential by hand, which for a mature instance with dozens of OAuth connections is a very bad week.
Second, the key must travel with the data. Migrating to a new server, restoring a backup, or running multiple n8n processes against one database (the queue-mode architecture in Chapter 33) all require every process to hold the same encryption key.
Watch out: Self-hosters: treat
N8N_ENCRYPTION_KEYas the single most important secret your instance has — more important than any individual credential, because it unlocks all of them at once. Store it in your password manager or secrets system, separately from your database backups. A backup of the database stored right next to the key that decrypts it is not defense, it is a bundle.
One more property worth knowing: the n8n editor is deliberately designed so that saved secret values are not casually readable back out of the UI, and when credentials are shared with other users (Chapter 34), those users can use the credential in their workflows without being shown its contents. Usage and visibility are separate privileges. That separation is real but not absolute — someone who can build and run workflows with a credential can ultimately make requests with it — which is exactly why the access controls in Chapter 34 exist.
Most credential fields accept static text, and static is what you want almost always. But n8n also allows expressions — the double-curly-brace language covered fully in Chapter 17 (Expressions: The Double-Curly-Brace Language) — inside credential fields. Instead of pasting a literal key, a field can contain an expression that resolves at execution time, for example reading a value from the data flowing into the node or from an environment variable.
When is this genuinely useful? The classic case is multi-tenant work:
one workflow that serves many customers, where the API key differs per
customer and arrives as part of the input data. An expression in the
credential field like {{ $json.customerApiKey }} lets a
single credential object serve them all. Another is keeping the secret
itself outside n8n entirely and referencing it from an environment
variable — a self-hosted pattern, since Cloud does not let you set your
own environment variables.
Understand the resolution rule before you rely on it: an expression in a credential field is evaluated in the context of the node using the credential, against the first item of its input. If your node processes a batch of items with differing keys, the batch does not get per-item credentials — the first item's key wins for the whole batch. Designs that need per-item authentication should loop so each execution handles one item (Chapter 9, Flow Control, covers looping patterns).
Watch out: A credential field fed by an expression is only as trustworthy as the data feeding it. If the key arrives from a webhook or a database, a malformed or malicious input becomes an authentication attempt. Validate upstream, and never let unauthenticated callers control which credential a workflow uses. For most builders, most of the time, static credential values are the right default — reach for expressions only when the multi-tenant shape genuinely demands it.
Everything so far assumed a dedicated integration — a Slack credential for the Slack node. But n8n can call any HTTP API through the HTTP Request node (the full treatment is Chapter 13, The HTTP Request Node: Talking to Any API), including the thousands of services with no dedicated node. Those calls still need authentication, and this is where generic credential types come in: credential shapes that mirror the raw authentication styles rather than any particular service.
In the HTTP Request node, the Authentication dropdown
offers two routes beyond None:
Predefined Credential Type lets the HTTP Request node borrow any service credential you already have. If you hold a Google credential, the node can use it to call Google endpoints the dedicated nodes don't cover — n8n signs the request correctly, including handling OAuth token refresh. Always check this route first: it is less work and more robust.
Generic Credential Type is for everything else.
Choosing it reveals a Generic Auth Type selector where you
pick the style the API demands and create a matching generic
credential:
X-API-Key
and friends) and, by setting the name to Authorization and
the value to Bearer followed by your token, plain bearer
tokens.Authorization: Bearer header for you, so you never have to
type the Bearer prefix yourself. (It does exactly what the
Header Auth trick above does, with one fewer field to get wrong.)The practical skill is translation. A provider's docs say:
"Authenticate by passing your secret key in the Authorization header as
a Bearer token." You read: generic auth, header or bearer type, done.
The docs say: "Append ?apikey=YOUR_KEY to all requests."
You read: query auth. Ten minutes of reading an API's authentication
page maps directly onto a two-field n8n form.
Why bother with a credential object at all, when the HTTP Request node would let you type a header by hand? Because a key typed directly into a node's parameters is stored with the workflow — visible to anyone who can read the workflow, included if you export or share the JSON, and sitting in plain text. The same key in a credential is encrypted at rest, hidden from casual view, and reusable across every workflow that needs it — an exported workflow carries only a reference to the credential (its name and ID), never the secret itself. Hand-typed secrets in node parameters are the single most common credential-hygiene mistake in real n8n instances.
Tip: Make it a personal rule: secrets live in credentials, never in node parameters, never in expressions as literals, never in Code nodes. If you ever paste a key anywhere other than a credential field, treat that key as leaked and rotate it.
A personal n8n instance accumulates credentials the way a kitchen drawer accumulates keys. Six months in, you will have dozens, and whether that collection is an asset or a hazard comes down to habits you set now.
Every credential should hold the minimum power the workflow actually needs. The principle cashes out differently per style:
For OAuth2, request only the scopes the workflow uses. A workflow that reads calendar events should carry a read-only calendar scope — not read-write, and not the kitchen-sink scope list that is tempting to grab "so I don't have to reconnect later." If a token leaks, its scopes are the blast radius.
For API keys, use the narrowest key the provider offers. Many services issue keys with configurable permissions or offer restricted key types; some distinguish test-mode keys from live ones. A payment provider's read-only test key and its full-access live key are wildly different objects — hold the dangerous one only where genuinely required.
For accounts, consider whose identity the automation should carry. A credential minted from your personal account means every automated action appears as you, and everything breaks if your account is suspended, downgraded, or offboarded. For anything durable, a dedicated service account — a machine-purpose account with exactly the memberships it needs — is the sturdier footing. Chapter 34 develops this into full team policy.
n8n auto-generates credential names, and left alone you will drift
into a list reading "Slack account," "Slack account 2," "Slack account
3" — indistinguishable at the moment you can least afford confusion.
Rename credentials at creation, and encode three facts: the service, the
identity or account, and the power or purpose.
Slack — #alerts bot — post-only and
Stripe — live — read-only reporting answer at a glance the
question every future debugging session will ask: which credential
is this, and what can it do? If you maintain separate credentials
for staging and production (the per-environment strategy in Chapter 35),
put the environment in the name too — it is the cheapest guardrail
against pointing a test workflow at live data.
Credentials age. Access tokens expire by design; n8n's OAuth2
handling refreshes them silently using the refresh token, which is why a
connected credential keeps working for months untouched. But refresh is
not immortality. Providers expire refresh tokens after long disuse or on
a fixed calendar; a password change or a security event at the provider
can revoke every delegated grant; an admin can deauthorize your app.
When that happens, the workflow that ran flawlessly for a year fails
with an authentication error, and the fix is human: open the credential
and click Reconnect (or its equivalent) to run the consent
dance again.
Plan for this instead of being ambushed by it. Know which of your credentials can die quietly — OAuth2 connections and any key with a stated expiry date top the list. Make sure an authentication failure in a production workflow reaches a human, via the error-handling patterns in Chapter 23 (Error Handling: Retries, Error Branches, and Error Workflows) and the monitoring in Chapter 25. And rotate deliberately: when you regenerate a key at the provider, update the n8n credential immediately — one object to edit, every workflow updated — and when a credential is no longer used by any workflow, delete it. One caveat before pruning: n8n does not currently give you a reliable everywhere-this-is-used view for a credential, so confirm nothing still references it — good names and a quick pass through the workflows that plausibly touch that service are your safety net. An unused live credential is pure downside: all the risk of a secret, none of the benefit.
Everything in this chapter treated credentials as yours alone. The moment a second person joins the instance, new questions appear: who may use a credential versus edit it, how role-based access control (RBAC — assigning permissions by role rather than person by person) and projects partition access, and whether secrets should live in n8n at all or be pulled at runtime from an external secrets vault such as HashiCorp Vault or a cloud provider's secret manager (an option on higher-tier plans). All of that is Chapter 34's territory. And when you graduate to separate development and production instances, the question of how credentials map across environments — same names, different secrets — is handled in Chapter 35 alongside source control. The habits here — least privilege, honest names, deliberate rotation — are the foundation both of those chapters build on.
Authentication styles are few, and they rhyme: a secret proves identity, the differences are in how the secret is issued, scoped, and carried. API keys and tokens are possession-is-proof strings; basic and header auth are delivery mechanics; OAuth2 is a protocol for delegating limited power without surrendering your password, with scopes as the boundary lines. n8n's contribution is separation of concerns: secrets live in encrypted credential objects, workflows merely reference them, and one encryption key — managed for you on Cloud, guarded by you when self-hosting — stands between your database and everything it protects. Create credentials from inside the nodes that need them, test them before trusting them, name them so your future self knows what they are, and give them no more power than the job requires. With that footing, the entire integration catalog in Chapter 12 opens up.
n8n's catalog runs to hundreds of built-in integrations — well past a thousand once community-built nodes and HTTP-reachable services are counted — and no one, not the people who build n8n, not the power users who live in it daily, has memorized them all. They do not need to, and neither do you. The catalog is navigable because nearly every node in it follows the same small grammar: a node type, a resource, an operation, a set of parameters, and a handful of recurring conventions for output shape, pagination, and optional settings. Learn that grammar once and you can open a node you have never seen before — a CRM you adopted yesterday, a database you inherited last week — and predict within a minute what it can do, what it cannot, and where its settings will be hiding.
This chapter teaches that grammar. It assumes you know how to add nodes to the canvas and wire them together (Chapter 8, Building the Action Chain) and that you have credentials sorted out (Chapter 11, Credentials from Zero). What it adds is the taxonomy: the categories the catalog is organized into, the conventions every node shares, how to read an n8n documentation page like a floor plan, and worked patterns for the five integration families almost every operator touches weekly — spreadsheets, email, chat, CRM, and databases.
Every node in the catalog belongs to one of two broad families, and knowing which family you are looking at tells you a lot before you read a single parameter.
Core nodes are the nodes that belong to n8n itself rather than to any outside service. They do the plumbing: receiving data (Webhook), calling arbitrary APIs (HTTP Request), reshaping data (Edit Fields, also called Set), making decisions (If, Switch), combining streams (Merge), running custom logic (Code), waiting (Wait), and so on. Core nodes mostly need no credentials because they talk to nothing external — the exceptions are the few that do reach outside, such as HTTP Request, which can carry credentials of its own. You will use a small set of core nodes in almost every workflow you ever build; they are covered in depth across Volumes B and D.
App nodes (the documentation also calls them "actions" or integration nodes) each wrap one external service: Google Sheets, Slack, Gmail, HubSpot, Notion, Stripe, Postgres, and the rest of the long tail. An app node is essentially a friendly costume over that service's API — the programmatic interface the service exposes so software can operate it. The node authors have done the tedious work of authentication, endpoint selection, and parameter formatting, and they present you with dropdowns and fields instead of raw HTTP. When an app node exists for your service, it is almost always the fastest path.
There is a third population worth naming: community nodes, integrations built and published by people outside the n8n core team, which you install separately. They follow the same grammar described in this chapter, but they vary in quality and maintenance. Finding, vetting, and installing them — and deciding when to build your own — is Chapter 15's territory.
Tip: When you open the node picker and search, n8n shows app nodes alongside the specific actions inside them ("Send a message in Slack", "Append row in Google Sheets"). Searching for the verb you want ("send email", "append row") is often faster than searching for the service name, because it drops you directly on the right operation instead of the node's front door.
Cutting across the core/app divide is a second taxonomy based on when and how a node runs. There are three shapes.
| Shape | What it does | Where it sits | Example |
|---|---|---|---|
| Regular node | Performs an action during a run, receiving items in and passing items out | Anywhere after the start of a workflow | Google Sheets, HTTP Request, If |
| Trigger node | Starts the workflow when something happens; it is the first node and has no input | Only at the start | Gmail Trigger, Webhook, Schedule Trigger |
| Cluster node (root plus sub-nodes) | A root node that does the main job, with sub-nodes plugged into special connectors underneath it to configure or extend it | Root sits in the flow like a regular node; sub-nodes hang off it | AI Agent (root) with a chat model, memory, and tools (sub-nodes) |
Regular nodes are the workhorses. Data flows into them from the left, they act on it (once per item, or once per batch, depending on the operation — Chapter 16 covers the item model that governs this), and results flow out to the right.
Trigger nodes answer the question "when should this workflow run?" Many app integrations exist in both flavors: there is a Slack node (regular — send messages, manage channels) and a Slack Trigger (start a workflow when a message arrives). In the node picker, both flavors appear under the same app entry — search for the service and you will see its actions and its triggers listed as separate groups — but they are separate nodes on the canvas, and the trigger flavor typically supports far fewer events than the regular flavor supports actions. Triggers come in polling variants (n8n checks the service on a schedule for anything new) and webhook variants (the service pushes events to n8n the moment they happen) — the trade-offs are Chapter 7's subject, and webhook mechanics get the full treatment in Chapter 14.
Cluster nodes are the newest shape, introduced for n8n's AI capabilities. A cluster is a root node — the AI Agent is the canonical example — plus one or more sub-nodes that attach to labeled connectors on the root's underside: a chat model sub-node supplies the language model, a memory sub-node supplies conversation history, tool sub-nodes supply abilities. The root defines what happens; the sub-nodes define with what. If you have only built classic workflows this shape looks alien the first time, but the underlying grammar is the same: each sub-node is still a node with parameters, credentials, and documentation of its own. The architecture is explained properly in Chapter 26 (AI Foundations and the Cluster-Node Architecture); for now it is enough to recognize the shape in the catalog so it does not surprise you.
Nodes evolve. The n8n team rewrites them — new operations, reorganized parameters, changed default behavior — and each significant rewrite is published as a new node version (internally a "type version"). Here is the part that matters operationally: a node on your canvas is pinned to the version it was created with. When you drag a Google Sheets node onto a workflow today, you get the latest version. The Google Sheets node you placed in a workflow eighteen months ago keeps running as the version it was born as, forever, even after you upgrade your n8n instance.
This is deliberate and it is protecting you. If nodes silently upgraded in place, an n8n update could change the behavior of hundreds of your production workflows overnight — parameters renamed, defaults flipped, output shapes altered. Pinning means an upgrade to n8n never rewrites the meaning of an existing workflow.
The practical consequences:
Ctrl/Cmd + C) and
paste it into a text editor, or download the workflow's JSON — either
way you will see the node's typeVersion field.Watch out: Copy-pasting nodes between workflows copies the version too. If you habitually clone an ancient "template" workflow as your starting point, every workflow you build inherits its elderly nodes. Periodically rebuild your personal templates from fresh nodes.
Open any app node and the parameter pane organizes itself around two dropdowns that between them define everything else you will see.
Resource is the noun: the kind of thing in the service you want to act on. In the Gmail node the resources include Message, Draft, Label, and Thread. In Slack: Message, Channel, User, File, and more. In a CRM: Contact, Company, Deal, and friends.
Operation is the verb: what to do to that noun. Create, Get, Get Many, Update, Delete, Send, Search — the exact list varies per resource, because it mirrors what the underlying API allows for that object.
Choose a resource and the operation list rebuilds to show only the verbs that exist for that noun. Choose an operation and the rest of the parameter pane rebuilds to show only the fields that operation needs. This is why an unfamiliar node is explorable rather than intimidating: click through the resources one by one, skim each one's operations, and in under a minute you have an accurate map of the node's entire capability surface. Nothing is hidden anywhere else — if a resource/operation pair does not exist in those two dropdowns, the node cannot do it.
That last sentence is the single most useful predictive rule in this chapter, so let it sink in: the resource and operation dropdowns are the node's complete table of contents. A node's capability is at most what the service's API offers, and often somewhat less, because node authors implement the popular endpoints first. When the thing you need is missing from the dropdowns, you have not failed to find it — it is not there, and your escape hatch is the HTTP Request node, which can call any endpoint the API offers using the very same credential (Chapter 13 teaches this, including the trick of borrowing an app node's authentication).
A related convention: many nodes let you specify which record to act on in multiple modes — pick from a list (n8n fetches your actual spreadsheets, channels, or contacts and shows a dropdown), by ID, or by URL. The list mode is friendliest; the ID mode matters the moment you need the target to be dynamic, computed by an expression from incoming data (Chapter 17 covers expressions). Nearly every such field accepts either a fixed value or an expression, and toggling between them is a core canvas skill from Chapter 8.
APIs are chatty. Ask Gmail for a message and the raw reply is a deeply nested envelope of headers, MIME parts (the packaging format email uses to bundle text, HTML, and attachments), thread metadata, and internal identifiers — dozens of fields, of which you probably want four. Many n8n nodes therefore offer a Simplify toggle (sometimes phrased as "Simplify Output"), usually on by default where it exists, which trims the response to the fields most people actually use: for an email, things like sender, recipient, subject, snippet, and labels.
Simplified output is the right default for building quickly. But you need to know two things about it:
Tip: While building, run a node once with Simplify off and skim the raw output even if you plan to leave simplification on. Thirty seconds of skimming tells you what the service knows about each record — which often reveals fields worth using that you did not think to ask for.
Any operation that fetches multiple records — usually named Get Many, Get All, Search, or similar — confronts the same problem: the service might hold ten records or ten million, and APIs never hand over ten million in one reply. They paginate: they return results a page at a time, with a token or offset to request the next page.
App nodes hide this behind a standard pair of controls:
That is the whole interface, and it is the same in nearly every app node: Google Sheets rows, Slack channel members, HubSpot contacts, Notion database pages. The pagination machinery — tokens, cursors, page sizes — is handled for you.
Two cautions. First, Return All means all: against a large dataset it can run for a long time, consume real memory on your instance, and hammer the service's rate limits (the caps services place on how many requests you may make per minute). If you only need recent records, prefer the operation's filter parameters (dates, status, search queries) over fetching everything and filtering inside n8n — filtering at the source is faster and kinder to everyone. Second, only the friendly app nodes do this for you. The HTTP Request node exposes pagination as a configurable option you set up yourself, because it cannot know an arbitrary API's paging style; that is part of Chapter 13. Pacing strategies for bulk work — batching, throttling, respecting rate limits — are reliability territory, covered in Chapter 24.
Watch out: A Get Many operation that returns exactly the default limit's worth of records is a classic silent truncation. Everything looks fine in testing with twelve records; in production with twelve thousand, you quietly process only the first page. Any time you see a suspiciously round number of results, check the Limit and Return All settings before trusting the data.
If resources and operations are a node's table of contents, the
Options section (sometimes labeled Additional Fields,
Filters, or simply Options, with an Add option or
Add Field button) is its appendix. This is a collection of
optional parameters that stay hidden until you explicitly add them,
keeping the default view uncluttered.
What lives there follows a pattern you will learn to anticipate:
The operational habit to build: whenever a node almost does
what you want — it sends the email but from the wrong alias, it appends
the row but mangles the date format — open the Options collection before
you reach for workarounds. A large fraction of "the node can't do X"
complaints dissolve inside Add option. Only when you have
exhausted the options collection and the resource/operation
dropdowns is it genuinely time for the HTTP Request escape hatch.
Every built-in node has a page on the official docs site
(docs.n8n.io), and the site's integrations section doubles
as a browsable version of the whole catalog when you want to scout
services without opening the editor. The pages all follow the same
layout. Reading one takes two minutes once you know the structure, and
it is the fastest way to scout a node before committing to it — or to
scout a service before committing to it, since the docs page
truthfully advertises how deep the integration goes.
A typical app node's documentation gives you:
Trigger nodes get their own separate pages, and cluster sub-nodes likewise. If you search the docs for a service name, expect two or three hits (node, trigger, credentials) — pick deliberately.
The prediction skill, condensed: service API defines the ceiling; the operations list defines what is actually built; the options collection defines the refinements; anything absent from all three does not exist in the node. Missing operation on an existing node → HTTP Request with borrowed credentials (Chapter 13). Missing node entirely → the community-node and build-your-own decision tree (Chapter 15).
The transferable skill this chapter has been building toward is translation: taking a thing you know how to do in a service's own UI and finding the resource/operation pair that does the same job. The five families below are the ones nearly every operator touches. For each, the pattern is the same — name the UI action, find the noun, find the verb, know the family's characteristic gotcha.
The Google Sheets node treats the document (the spreadsheet file) and the sheet (a tab within it) as its resources, with the sheet resource carrying the operations you will actually use daily. The UI-to-operation translations:
The characteristic gotcha: a spreadsheet's column headers are its schema. The node maps item fields to columns by header name, so renaming a column in the sheet silently breaks the mapping. Treat header rows in automated sheets as frozen infrastructure.
The two nodes rhyme rather than match, which makes them a good lesson in reading resources: Gmail's are Message, Draft, Label, and Thread, while Outlook's cover messages, drafts, and folders — Outlook files mail into folders where Gmail applies labels, and the node vocabularies follow each service's own model. Translations:
Gotchas: email bodies come in text and HTML variants — be explicit about which you are sending, because HTML in a plain-text field arrives as visible tag soup. Attachments are binary data, which n8n carries alongside JSON in a separate channel; sending and receiving them correctly depends on the binary-data model from Chapter 20. And with Simplify on, message bodies may be trimmed or represented as snippets — turn it off when you need the full text.
Resources include Message, Channel, User, File, and Reaction. Translations:
The family gotcha: chat platforms authenticate you as a bot, and a bot is a member like any other. A Slack bot cannot post to a channel it has not been invited to, and an error like "not in channel" or "channel not found" very often means "channel exists, bot isn't in it" — the latter is what Slack returns for a private channel the bot cannot even see. When a chat node fails, check the bot's membership and its permission scopes (defined when the credential's app was configured — Chapter 11) before debugging the workflow.
CRMs differ in vocabulary but rhyme structurally: resources for Contact, Company/Organization, and Deal/Opportunity, plus notes and activities. Translations:
The gotcha, generalized: CRMs are the most configured systems you will integrate — your pipelines, stages, and custom fields are unique to your instance, so the node can offer structure but you must supply your instance's identifiers. Expect a one-time scavenger hunt per CRM.
You do not need to write SQL — the query language of relational databases — to use these nodes at the level most operators need. The nodes offer spreadsheet-like operations against tables: insert rows, update rows matched on a column, select rows with simple conditions, delete matched rows, mapping incoming item fields to table columns much as the Google Sheets node maps them to sheet columns. Translations from spreadsheet thinking: append row → insert; update-by-key → update with a match column; lookup → select with a condition.
Two family-specific notes. First, each of these nodes also has an execute-query operation that runs raw SQL you write — that is the database equivalent of the HTTP Request escape hatch, and it belongs to Chapter 19's "when clicks are not enough" territory. Second, databases enforce their schema in a way spreadsheets do not: a text value aimed at a numeric column is an error, not a quiet coercion. The error messages are actually more helpful than most API errors — read them; they usually name the offending column.
Watch out: Database nodes are the sharpest tools in this chapter. An update or delete operation with a wrong or missing match condition can modify every row in the table, and there is no undo. Test against a copy of the data, or at minimum run the matching logic as a select first and inspect what comes back before switching the operation to update or delete.
The next time you face an unfamiliar node, run this drill, in order, before searching forums or asking anyone:
Do this a dozen times and it stops being a drill. The catalog stops being a thousand products and becomes one product with a thousand skins — which is what it was all along.
n8n ships with hundreds of dedicated integration nodes, and Chapter 12 (Navigating and Operating the Integration Catalog) showed you how to find and drive them. But sooner or later you will hit a wall: the service you need has no dedicated node, or the node exists but lacks the one operation you want, or a brand-new API feature has not made it into the node yet. The HTTP Request node is the answer to all three. It is a general-purpose tool that can call essentially any web API on the internet, which makes it the single most powerful node in the palette — and the one that asks the most of you, because you assemble the request yourself instead of picking operations from a dropdown.
The good news: a web request has only a handful of moving parts, and once you can name them, third-party API documentation stops looking like a foreign language. This chapter builds that literacy from zero, then walks through every part of the node — methods, URLs, query parameters, headers, bodies, all the authentication options, importing a curl command, pagination, batching, and reading responses. The contract for this chapter is getting the call to work. What to do when a working call occasionally fails — retries, backoff, error branches — belongs to Chapter 23 (Error Handling: Retries, Error Branches, and Error Workflows) and Chapter 24 (Reliability Patterns: Idempotency, Pacing, and Recovery). And the agent-facing variant of this node, where an AI model decides what to call, is covered in Chapter 28 (The AI Agent Node: Tools, Memory, and Guardrails).
Every interaction with a web API — an API being a service's machine-facing front door, its Application Programming Interface — is a request you send and a response you get back. The request has five parts, and the HTTP Request node has a field or section for each one.
The method (sometimes called the verb) tells the server what category of action you intend. There are only a few you will ever use:
| Method | What it means | Typical use |
|---|---|---|
| GET | Read something; no changes | Fetch a contact, list invoices, search records |
| POST | Create something, or perform an action | Create a ticket, send a message, run a search with a complex query |
| PUT | Replace something entirely | Overwrite a record with a full new version |
| PATCH | Update part of something | Change one field on a record |
| DELETE | Remove something | Delete a record, revoke a token |
| HEAD | Like GET but return only headers | Check whether a resource exists without downloading it |
| OPTIONS | Ask the server what is allowed | Rarely needed in workflows |
You do not choose the method — the API's documentation tells you
which method each operation expects. If the docs say "POST
/v2/contacts", you set the node's Method to POST and put
the full address (the base URL joined to that path, as the next section
explains) in the URL field. Using the wrong method is one
of the most common beginner errors, and the server usually answers with
a status code of 404 or 405 (more on codes later).
The URL is the address. It usually breaks into a base URL that is the
same for every call to a given service (something like
https://api.example.com/v2) and a path that names the
specific resource (/contacts or
/contacts/12345). API docs almost always state the base URL
once, near the top, then list only the paths for each operation — you
join the two yourself.
Watch for path parameters: when documentation writes
/contacts/{id} or /contacts/:id, the curly
braces or colon mark a placeholder you must replace with a real value.
In n8n you typically do that with an expression, so the URL field might
contain
https://api.example.com/v2/contacts/{{ $json.contactId }} —
the double-curly-brace expression language from Chapter 17 (Expressions:
The Double-Curly-Brace Language) works in every field of this node.
Query parameters are the ?status=open&limit=50 part
you sometimes see at the end of a URL — a list of name–value pairs the
server reads as options. They are most common on GET requests: filters,
sort orders, page sizes, search terms. You could type them straight into
the URL field, but do not. Enable the node's
Send Query Parameters toggle and add each name and value as
its own row instead. n8n then handles URL encoding for you — the fiddly
business of turning spaces and special characters into the
%20-style sequences URLs require. A search term containing
an ampersand will silently break a hand-typed URL and work perfectly as
a parameter row.
Headers are name–value pairs that ride along with the request and describe it: what format you are sending, what format you accept back, who you are. Common ones you will meet:
Content-Type — the format of the body you are sending,
almost always application/json. n8n sets this automatically
when you use its JSON body option.Accept — the format you want back; some APIs require
application/json here.Authorization — where credentials usually travel, for
example Bearer <token> (a bearer token being a secret
string that grants access to whoever presents it). In n8n you should let
the credential system fill this rather than typing it yourself; the
authentication section below explains why.X-Api-Version or an account identifier. The docs will say
so explicitly.Enable Send Headers and add rows for whatever the
documentation demands beyond what n8n and your credential already
provide.
GET and DELETE requests usually have no body. POST, PUT, and PATCH
requests almost always do — the body is the payload, the actual data.
Enable Send Body and pick a
Body Content Type:
{ "name": "Ada", "email": "ada@example.com" }. In the
node you can build it either as individual name–value fields (easiest,
and each value can be an expression) or by switching to a raw JSON view
and writing the whole document, expressions included. Use the fields
view until you need nesting the fields cannot express.The API documentation always shows an example body. Your job is to reproduce its shape and swap the example values for expressions that pull real data from your incoming items.
API docs are written by developers for developers, but they follow a predictable template, and you only need five sections of it. When you open the documentation for any service, hunt for these in roughly this order:
The base URL. Usually in a "Getting started" or "Making requests" page. Copy it somewhere; every call you build starts with it. Watch for regional variants — some services use different base URLs per data center, and your account belongs to exactly one.
The authentication section. Before anything works, you must know how the API expects you to prove who you are: an API key in a header, a bearer token, basic auth, or OAuth (a scheme where you register an "app" with the service and it issues expiring tokens, rather than handing you a permanent key). This section tells you which, and where to create the key or app in the service's own settings. Chapter 11 (Credentials from Zero) covers obtaining and storing these safely; here you only need to identify the mechanism.
The endpoint reference. The big index of operations — an endpoint being one URL-plus-method combination that does one thing. Find the operation you want and note four things: the method, the path, the required parameters (docs usually mark each parameter required or optional, and say whether it goes in the path, the query string, or the body), and the example request.
The example request. Nearly every API doc shows examples as curl commands — curl is a command-line tool for making web requests, and its syntax has become the lingua franca of API examples. You do not need to read curl fluently, because n8n can import these commands directly; the section below shows how.
Rate limits and pagination. Two short sections that save you hours later. Rate limits state how many requests you may make per second or minute before the server starts refusing you with a 429 status. Pagination explains how list endpoints split long results across multiple requests. Skim both now; you will use them at the end of this chapter.
Tip: Many API docs have an interactive "try it" console where you can run a request in the browser with your own key. Use it to get one successful call working before you build anything in n8n. Once you have seen a real response, you know your credentials work and what shape the data comes back in — which turns n8n troubleshooting from "is anything right?" into "what did I copy wrong?"
A few vocabulary landmines, translated once: a REST API just means an API organized around URLs and the standard methods above; a payload is a body; a resource is a thing the API manages (a contact, an invoice); 201 Created and friends are status codes, decoded near the end of this chapter; and an SDK is a code library you can ignore entirely — n8n replaces it.
Add the node the usual way (canvas mechanics are Chapter 8's subject
— see Chapter 8, Building the Action Chain: Canvas and Node Mechanics):
open the node picker, search for "HTTP Request", and drop it after
whatever supplies its input. The parameter panel presents the pieces in
the order you just learned them: Method, URL,
Authentication, then the three toggles —
Send Query Parameters, Send Headers,
Send Body — each of which unfolds into rows when
enabled.
Two habits make this panel pleasant to work with. First, prefer the row-based "fields" mode for parameters, headers, and JSON bodies, and switch any individual value to an expression when it needs data from the incoming item. Second, when you do need hand-written JSON, switch that section to its JSON mode and paste the documentation's example body as a starting skeleton, then replace values with expressions one at a time, executing the node after each change.
One structural fact governs everything else: like most n8n nodes, the HTTP Request node runs once per incoming item. Feed it one item, it makes one request. Feed it fifty items, it makes fifty requests, each with expressions resolved against its own item. This is exactly what you want for "create a ticket for every row" — and exactly what you do not want when you meant to call an API once. Chapter 16 (Reading and Reasoning About Data: The Item Model in Practice) covers the item model in full, including how to collapse many items into one when a single call is the goal.
Watch out: The one-request-per-item behavior is the classic way to accidentally hammer an API. If a node upstream unexpectedly emits 500 items, your innocent-looking HTTP Request node just made 500 calls — possibly 500 writes. While building, pin a small, known input on the previous node (pinning is covered in Chapter 10, Test, Fix, Activate, and Keep It Tidy) so you always know exactly how many requests an execution will fire.
The node's Authentication field has three top-level
choices, and picking the right one is mostly a decision tree.
None. For genuinely open APIs — public data sources, some webhook-style endpoints. Rare in practice.
Predefined Credential Type. This is the option most people overlook and the one you should reach for first. n8n's dedicated integration nodes each know how to authenticate against their service — where the token goes, how OAuth refresh works. The Predefined Credential Type option lets the HTTP Request node borrow that knowledge: you pick the service by name from a list (the same catalog of credential types that powers the dedicated nodes), select or create a credential exactly as Chapter 11 describes, and n8n signs the request for you. You get the full flexibility of a hand-built request with none of the authentication plumbing. This is the standard pattern for "the Slack/HubSpot/Google node exists but lacks the operation I need": same credential you already made for the dedicated node, custom URL and body of your choosing.
Generic Credential Type. For services n8n has no credential type for. You choose the mechanism yourself, matching whatever the API documentation specified:
| Generic type | How it works | When the docs say... |
|---|---|---|
| Bearer Auth | You supply only the token; n8n builds the
Authorization: Bearer <token> header for you |
"Bearer token", or a curl example with
-H "Authorization: Bearer ..." |
| Header Auth | Sends any name–value pair you define as a header | "Pass your API key in the X-Api-Key header" |
| JWT Auth | You supply a signing secret (or key pair) and the claims; n8n signs
a JSON Web Token — a compact, self-contained signed token — and sends it
in the Authorization: Bearer <token> header |
"Sign a JWT", "JSON Web Token", "signed token with your secret" |
| Basic Auth | Username and password, encoded into an Authorization
header |
"HTTP basic authentication" or a curl example with
-u user:pass |
| Query Auth | Sends a name–value pair as a query parameter | "Append ?api_key=... to the URL" |
| Digest Auth | A challenge–response variant of basic auth | "Digest authentication" (uncommon; some devices and older systems) |
| OAuth2 API | Full OAuth 2.0 flow with token refresh handled by n8n | "Create an OAuth app", "client ID and secret", "authorization code" |
| OAuth1 API | The older OAuth 1.0a signing scheme | Legacy APIs only |
| Custom Auth | You define a combination of headers, query parameters, or body fields | The scheme fits none of the above, or needs several pieces at once |
Whichever you choose, the values live in a credential — created and stored through the same encrypted credential system as everything else in Chapter 11 — not in the node.
Watch out: It is entirely possible to skip the credential system and paste an API key straight into a header row or the URL. Do not. Anything typed into node parameters is saved in the workflow itself, visible to anyone who can open the workflow, included if you export or share the JSON, and displayed in execution logs. Credentials exist precisely so secrets are stored encrypted and referenced, never embedded. If you imported a curl command that contained a live key (next section), your first act should be moving that key into a credential and deleting it from the node.
One nuance worth knowing: OAuth2 in "client credentials" mode (machine-to-machine, no human consent screen) and OAuth2 in "authorization code" mode (a person clicks through a consent screen once) are both handled by the generic OAuth2 credential; the API docs will tell you which grant type the service uses, and the credential form has a field for it. After the initial setup, n8n refreshes expiring tokens automatically — one of the strongest arguments for never managing tokens by hand in header fields.
At the top of the HTTP Request node's panel is an
Import cURL button. Paste any curl command into it and n8n
dissects the command and fills in the node for you: method, URL,
headers, query parameters, body, all placed in the right sections. Since
nearly every API's documentation provides its examples as curl, this is
often the fastest path from "reading docs" to "working node": copy the
example for your endpoint, import it, then customize. Note that
importing replaces whatever the node already contained, so import first
and customize after — not the other way around.
Three things to fix after any import. First, replace placeholder
values — docs write YOUR_API_KEY or
{contact_id} and the importer faithfully copies them in;
swap secrets into a credential (choose an authentication option and
delete the imported auth header) and placeholders into expressions.
Second, check the body made it across; a multi-line JSON body with
unusual shell quoting occasionally confuses the importer, and pasting
the JSON manually into the body section takes seconds. Third, re-read
what was imported before you run it — the example may target a "create"
endpoint when you only meant to read.
Curl commands copied from documentation often span several lines joined by backslashes (or carets, in Windows examples). The importer copes with the common cases, but if an import comes out mangled, paste the command into a text editor first, join it onto one line, and re-import. And if the browser's developer tools offer "Copy as cURL" on a network request, that works too — a handy trick for replicating a call you watched a web app make.
When the request succeeds, the response body becomes the node's output. n8n auto-detects the format by default: a JSON response is parsed into structured fields you can use downstream like any other item data, plain text arrives as a text field, and files arrive as binary data. You can override the detection in the node's options — forcing text is occasionally useful when a server mislabels its JSON, and forcing file is how you download something regardless of its declared type.
Shape matters here. If the API returns a single JSON object, you get
one item. If it returns a JSON array of twenty objects, n8n splits it
into twenty items automatically — usually exactly what you want, since
each can then flow through the rest of the workflow independently. If
the API wraps its array inside an envelope object (very common:
{ "data": [...], "meta": {...} }), you get one item
containing the envelope, and you will want the array split out — the
Split Out node from Chapter 18 (The Transformation Toolkit) does it in
one step.
By default the output contains only the response body. In the node's options you can ask for the response headers and status code to be included alongside the body. Turn this on when you genuinely need that metadata — for instance, when an API returns useful headers like remaining-rate-limit counts, or when a 201-versus-200 distinction matters to your logic.
There is also an option that stops the node from treating error status codes as failures, letting 4xx and 5xx responses flow through as ordinary data for you to inspect and branch on. That option is a building block for the error-handling strategies of Chapter 23; while you are still getting the call working, leave it off so failures are loud.
List endpoints rarely return everything at once. To keep responses small, APIs paginate — they hand you results a page at a time and expect you to come back for the next page. The documentation's pagination section will describe one of a few schemes:
| Scheme | How it works | Telltale signs in the docs |
|---|---|---|
| Page number | You pass page=1, then page=2, ... |
Parameters named page, sometimes
per_page |
| Offset and limit | You pass offset=0&limit=100, then
offset=100, ... |
Parameters named offset/skip and
limit |
| Cursor | Each response includes an opaque token you pass to get the next page | Fields named cursor, next_cursor,
next_page_token |
| Next URL | Each response includes the complete URL of the next page | A next field, or a Link response
header |
The HTTP Request node has pagination support built in, under its
options. You choose between two modes that cover all four schemes:
update a parameter on each request (for page numbers, offsets, and
cursors — the parameter's value is an expression that can reference the
previous response and a built-in page counter), or follow a next URL
taken from the response (for the next-URL scheme, the expression points
at wherever the response keeps it). You then tell n8n when to stop: when
a response comes back empty, when a particular status code arrives, or
when an expression you write evaluates to true (for example, when the
response's has_more field is false) — and you can cap the
maximum number of pages as a safety net. Within pagination's own
settings you can also add a pause between page requests to stay
polite.
Configured this way, the node silently makes as many requests as needed and returns the combined results as its output — downstream nodes never know pagination happened. When you build one, start with the max-pages cap set low, execute, confirm the pages stitch together correctly, then raise or remove the cap.
Watch out: An expression mistake in pagination — a stop condition that never becomes true, or a cursor field name typo that makes every "next page" identical — can produce a node that requests page after page forever, burning your rate limit and stalling the execution. Always set the maximum-pages cap while developing pagination, and only lift it once you have watched a run stop on its own for the right reason.
When the node runs once per item across a large input, it fires those requests in quick succession — quicker than many APIs allow. The node's batching options exist for exactly this: you set how many items to process per batch and how long to pause between batches, and n8n spaces the requests out accordingly. If the API's docs say "no more than N requests per minute," a little arithmetic gives you a batch size and interval that stay comfortably under it.
Batching is pacing at its simplest, and for many workflows it is all you need. The fuller discipline — respecting rate-limit headers, backing off when you are told to slow down, recovering cleanly mid-run — is Chapter 24's subject (Reliability Patterns: Idempotency, Pacing, and Recovery), and what to do when a request fails outright is Chapter 23's. This chapter's contract ends at requests that succeed when circumstances are normal.
Every response carries a three-digit status code — the server's one-line verdict on your request. The first digit tells you the family; the specific codes below cover nearly everything you will meet:
| Code | Name | What it means for you |
|---|---|---|
| 200 | OK | Success; the body has your data |
| 201 | Created | Success; the thing was created (body usually contains it) |
| 204 | No Content | Success, deliberately empty body — not an error |
| 301 / 302 | Redirect | The resource moved; n8n follows redirects by default, so you rarely see these |
| 400 | Bad Request | The server could not understand your request — usually malformed JSON, a missing required field, or a wrong parameter type |
| 401 | Unauthorized | Authentication failed: missing, wrong, or expired credentials |
| 403 | Forbidden | Authenticated, but not allowed — the key lacks a permission or scope |
| 404 | Not Found | Wrong URL or path, or an ID that does not exist. Also what some APIs return instead of 403, to avoid confirming a resource exists |
| 405 | Method Not Allowed | Right URL, wrong method — check GET versus POST |
| 409 | Conflict | The request collides with current state, such as creating a duplicate |
| 415 | Unsupported Media Type | Wrong or missing Content-Type header |
| 422 | Unprocessable Entity | The JSON was valid but the values failed validation; the body usually says which field |
| 429 | Too Many Requests | You hit the rate limit — slow down (batching above; strategy in Chapter 24) |
| 500 | Internal Server Error | The server broke; often transient, sometimes triggered by unusual input |
| 502 / 503 / 504 | Bad Gateway / Unavailable / Timeout | The service or something in front of it is struggling; usually temporary |
The rule of thumb: 4xx codes mean you need to change something — the request is wrong somehow — while 5xx codes mean the server is having trouble and the same request may well succeed later. Error responses usually include a JSON body explaining the problem in more detail; when a node fails, read that body in the error output before changing anything. The systematic version of that craft is Chapter 22 (The Debugging Craft), and Chapter 39 (The Troubleshooting Encyclopedia) catalogs specific error messages.
Tip: A stubborn 401 with credentials you are sure are right is usually one of three things: the key was pasted with a stray space or missing prefix (a Bearer Auth credential adds the word
Bearerand the space for you; a Header Auth credential sends exactly what you typed, prefix included or not), the key belongs to a different environment (test versus live, or the wrong region's base URL), or the token expired and the service issues short-lived tokens you should be handling via an OAuth2 credential instead of a static header.
Beyond batching, pagination, and response handling, the node's
options collect a grab-bag of switches you will occasionally need. A
timeout setting bounds how long n8n waits before giving up on a slow
server — worth setting deliberately on APIs known to dawdle. Redirect
behavior is configurable if an API misuses redirects and you need to see
them rather than follow them. A proxy setting routes the request through
an intermediary, which some corporate networks require. An option
controls how array values are formatted in query strings, because APIs
disagree about whether repeating a parameter should look like
id=1&id=2, id[]=1&id[]=2, or
bracketed-and-numbered variants — if a multi-value filter is being
ignored, this is why. And there is an option to skip SSL certificate
verification — the check, behind every https:// connection,
that the server really is who it claims to be — for servers with broken
or self-signed certificates (certificates a server vouches for itself,
with no trusted authority behind them).
Watch out: Turning off SSL verification tells n8n to trust any server claiming to be your API, which quietly removes the protection that keeps credentials from being intercepted. It is sometimes a pragmatic necessity for an internal service on your own network with a self-signed certificate — and it is never the right fix for a public API. If a public API shows certificate errors, the problem is elsewhere (often the machine's clock or network) and disabling verification just hides it.
You can now take any API's documentation and turn it into a working node: identify the base URL and auth scheme, import the example curl command, wire the credential through a predefined or generic type, replace placeholders with expressions, and read the response with the item model in mind — paginating and batching when the data is large. That skill quietly upgrades everything else in this book, because every dedicated node is ultimately doing what you just learned to do by hand, and now none of them is a ceiling. When a call needs to survive the real world's failures, continue to Chapter 23 and Chapter 24; when you want to receive requests instead of send them, Chapter 14 (Webhooks In Depth: Receiving Data and Building Endpoints) is the mirror image of this chapter; and when an AI agent should decide which calls to make, Chapter 28 hands this same capability to a model — with guardrails.
Most triggers in n8n work by asking. A Schedule Trigger asks the clock; a polling trigger asks an app "anything new?" every few minutes. A webhook inverts that. A webhook is an HTTP request that another system sends to a URL you control, at the exact moment something happens — a payment clears, a form is submitted, a support ticket is opened. Instead of your workflow checking repeatedly, the other system knocks on your door once, with the data already in hand. Chapter 7 (Triggers: Deciding When Work Happens) covered when to prefer webhooks over polling. This chapter covers how they actually work in n8n: the Webhook node's URLs, paths, and methods; the difference between test and production URLs; the authentication options that keep strangers out; the response modes that decide what the caller hears back; and the Respond to Webhook node, which lets you build genuine small API endpoints out of ordinary workflows. It ends with the pattern that turns n8n into a true integration hub: webhook in, HTTP Request out.
Drag a Webhook node onto an empty canvas and n8n immediately mints
you a URL. That URL is a real, publicly reachable address on the
internet. On n8n Cloud it lives under your instance's own domain; on a
self-hosted instance it lives under whatever public address your server
presents (getting that address right is a setup concern covered in
Chapter 32, Self-Hosting from Zero — if your instance thinks it lives at
localhost, the URLs it hands out will be useless to the
outside world).
The node has three settings that define the shape of your endpoint:
HTTP Method. HTTP requests come in flavors called
methods: GET asks for data, POST sends data,
and PUT, PATCH, and DELETE round
out the common set. Your Webhook node only answers the method you
configure — a POST to a webhook configured for
GET is rejected. Most third-party apps deliver webhooks as
POST requests with a JSON body, so POST is the
default and the right choice most of the time. Recent versions of n8n
also let a single Webhook node accept several methods at once — turn on
Allow Multiple HTTP Methods in the node's options — which
matters when you build API-style endpoints later in this chapter; each
accepted method then gets its own output connector on the node, so
GET handling and POST handling flow into
separate branches from the start.
Path. The path is the part of the URL after the
fixed prefix. n8n generates a long random identifier by default —
something like a UUID (a universally unique identifier, a 36-character
random string). You can replace it with something readable like
new-lead or stripe-events. You can also
declare route parameters: a path like
orders/:orderId matches orders/1234 and
orders/9876, and hands you the variable piece as data. That
is the trick that turns one workflow into a lookup API. One constraint
to know: across all active workflows on an instance, a given
path-plus-method combination must be unique. If you activate a second
workflow whose webhook claims the same path and method, n8n refuses with
a conflict error — the fix is simply to give one of them a different
path.
Authentication. By default: none. We fix that in a later section; do not skip it.
Tip: The random default path is not laziness — it is a security feature. A path nobody can guess is your first line of defense. If you rename it to something friendly like
contact-form, you have made it guessable, so pair a friendly path with one of the authentication options described below. For endpoints only machines will ever call, keeping the random path is a perfectly good choice.
When a request arrives, the Webhook node produces one item (Chapter 3 introduced items; Chapter 16 works with them in depth) whose JSON is neatly compartmentalized:
headers — the HTTP headers the caller sent: content
type, user agent, any signature headers, and so on.params — the values captured by route parameters, if
your path declared any.query — the query string, meaning anything after a
? in the URL, parsed into fields.body — the payload itself, parsed from JSON or form
data into ordinary fields.There are also a couple of metadata fields, including one that tells
you whether the call came in through the test or the production URL —
occasionally handy for branching behavior during development. When you
reference this data in later nodes, remember the compartments: the
customer email in a JSON payload is {{ $json.body.email }},
not {{ $json.email }}. Forgetting the body.
prefix is one of the most common beginner stumbles with webhooks
(expressions themselves are Chapter 17's territory).
Open the Webhook node and you will see two URLs, presented as tabs: a
Test URL and a Production URL. They
differ only in a path segment — the test URL contains a
webhook-test marker where the production URL has
webhook — but they behave completely differently, and
confusing them is the single most common webhook problem in
practice.
The test URL exists for building. It only listens
when you tell it to: click Listen for test event (or
execute the workflow from the editor) and the URL goes live, waits for
one request, feeds it into the canvas so you can watch data
flow through your nodes, and then stops listening. This one-shot
behavior is deliberate — it gives you a real payload to build against
without leaving a door open. If you send a second request without
re-arming the listener, the caller gets an error response and nothing
happens in n8n.
The production URL exists for running. It only works when the workflow is active — the toggle at the top of the editor, covered in Chapter 10 (Test, Fix, Activate, and Keep It Tidy). Once active, the production URL listens continuously, every delivery starts a fresh execution, and those executions do not appear live on your canvas. They run in the background and are recorded in the executions list (Chapter 21, Executions: The System of Record), which is where you go to see what production traffic actually did.
Watch out: The two failure modes to burn into memory: (1) you registered the test URL in a third-party app, it worked once while you were listening, and then "mysteriously stopped" — because the test URL only listens on demand; (2) you registered the production URL but forgot to activate the workflow, so every delivery bounces. When a webhook "doesn't work," check which URL is registered and whether the workflow is active before debugging anything else.
The practical rhythm: build against the test URL, clicking
Listen for test event and triggering real events from the
source app until your workflow handles the payload correctly; then
activate the workflow and update the registration in the source app to
the production URL.
Every HTTP request expects a response — at minimum a status code (a three-digit number where the 200s mean success, 400s mean the caller erred, and 500s mean the server erred). The Webhook node's Respond setting decides what your endpoint says back, and choosing correctly matters more than it first appears.
| Response mode | What the caller receives | When to use it |
|---|---|---|
| Immediately | A quick acknowledgment as soon as the workflow starts, before any real work happens | Notifications from third-party apps; anything where the caller only needs to know "received" |
| When Last Node Finishes | The data produced by the final node of the workflow, once everything has run | Simple request–response endpoints where the whole workflow is fast |
| Using 'Respond to Webhook' Node | Whatever a Respond to Webhook node in the workflow explicitly sends, at the moment that node runs | Real API endpoints: custom status codes, custom bodies, different responses on different branches |
Newer versions add one more option: a streaming response, which sends output progressively as the workflow generates it. It exists for AI chat endpoints, where a person watches an answer appear word by word (Volume F's territory); classic webhook senders neither expect nor benefit from it.
Two forces shape the choice. First, timeouts: the
systems that send webhooks wait only a short time for a response —
typically seconds — and treat silence as failure, often retrying the
delivery. If your workflow does slow work (calling several APIs,
invoking an AI model), a caller waiting on "When Last Node Finishes" may
give up and redeliver, and now you have duplicate executions. A
held-open synchronous response is doubly fragile: n8n itself, and any
reverse proxy (a server that sits in front of yours and relays requests
to it) fronting a self-hosted instance (Chapter 32), impose their own
response timeout, so a long run can have its connection cut even when
the execution completes cleanly. The cure is the acknowledge-fast,
work-after pattern: respond Immediately, then take as
long as you need. Second, who is listening: a machine
delivering an event notification ignores your response body entirely, so
there is no point crafting one; a machine asking a question
(the API-endpoint case) cares about nothing else.
For "When Last Node Finishes," the node's options let you choose what to return — the first item's JSON, the first item's binary file, all items, or no body at all — and set the response code. For anything more ambitious, use the third mode and read on.
Tip: When a webhook provider retries deliveries you actually processed (because your response arrived too slowly), you get duplicates. Respond
Immediatelywhenever the caller does not need real data back, and make the workflow idempotent — safe to run twice on the same event — using the techniques in Chapter 24 (Reliability Patterns: Idempotency, Pacing, and Recovery).
Set the Webhook node's Respond setting to
Using 'Respond to Webhook' Node and you unlock the most
interesting capability in this chapter: workflows that behave like
hand-built API endpoints, without a server, a framework, or a deploy
pipeline.
The Respond to Webhook node is an ordinary node you
place anywhere downstream of the Webhook trigger. When execution reaches
it, the HTTP response goes out; nodes after it keep running, but the
caller has already been answered. Its Respond With
setting covers the useful cases: a fixed or expression-built
JSON body, plain Text, the
First Incoming Item or All Incoming
Items flowing into it, a Binary File (send
back a PDF or image — binary data is Chapter 20's subject), a
Redirect to another URL, or No Data
when only the status code matters. Its options let you set the HTTP
response code and any response
headers, such as Content-Type.
The pattern that makes this powerful is branching to different responses. Because Respond to Webhook is a normal node, you can place one on each branch of an If or Switch node (Chapter 9, Flow Control):
400 and
{ "error": "email is required" }.404 and a not-found
body.200 and the real payload.Combine that with route parameters and you have a genuine read API in
five nodes: a Webhook node on GET with path
customers/:id, a data lookup using
{{ $json.params.id }}, an If node checking whether anything
came back, and two Respond to Webhook nodes for the found and not-found
cases. Whoever calls .../webhook/customers/1042 gets a JSON
answer, and from the outside it is indistinguishable from a
purpose-built microservice. This is superb for internal tools, quick
integrations between your own systems, and giving a spreadsheet or
dashboard something to fetch. It is not the right foundation for a
high-traffic public API — n8n executions carry more overhead per request
than a dedicated web server, and Chapter 33 (Scaling and Performance)
explains what heavy webhook traffic requires. Know the tool's weight
class and it will serve you well. (Exposing workflows as tools for
AI agents over MCP is a different mechanism entirely — see Chapter
30.)
One rule of hygiene: when the Webhook node is set to use a Respond to Webhook node, make sure every possible path through the workflow actually reaches one. A branch that dead-ends without responding leaves the caller hanging until a timeout, which reads as an outage from the outside.
Your production URL is reachable by anyone on the internet who knows or guesses it. Before a webhook workflow touches real data, decide deliberately how it tells friends from strangers. n8n gives you several independent layers; use at least one, and for anything sensitive, two.
Built-in inbound authentication. The Webhook node's Authentication setting supports a few schemes, each backed by a credential you create the usual way (Chapter 11, Credentials from Zero):
| Option | How the caller proves itself | Best for |
|---|---|---|
| Basic Auth | A username and password sent in a standard
Authorization header |
Systems and people that support classic HTTP authentication |
| Header Auth | A secret token in a header name you choose (for example
X-Api-Key) |
Most third-party apps and your own scripts — the workhorse option |
| JWT Auth | A signed token (JSON Web Token) the node verifies cryptographically | Callers that already issue JWTs; more setup, stronger guarantees |
| None | Nothing | Only alongside another defense, such as signature verification |
Header Auth is the pragmatic default: nearly anything that can send a webhook can also attach a custom header, and rotating the secret means updating one credential. Note that whichever scheme you choose guards both the test and production URLs — remember to configure the secret in the sending app before wondering why deliveries return an authorization error.
IP allowlisting. The node's options include an IP allowlist (accept requests only from addresses you specify). When a provider publishes the fixed IP addresses it delivers from, this is a strong extra layer. When the caller's addresses change or are undocumented, skip it rather than playing whack-a-mole.
Signature verification. The gold standard, covered in its own section below, because it deserves the space.
Smaller dials worth knowing. The options list also includes an ignore bots switch, which drops requests from link-preview crawlers and similar automated user agents — useful when your webhook URL might get pasted into a chat app that eagerly "previews" links, firing your workflow. An allowed origins option controls CORS (cross-origin resource sharing — the browser rule governing which websites' front-end code may call your endpoint); it matters only when browsers call your webhook directly from a web page, and should then list exactly the sites you expect. And everything rides over HTTPS — encrypted HTTP — by default on n8n Cloud; self-hosters must ensure the same (Chapter 32). Team-level concerns like who may edit these workflows and where secrets live are Chapter 34's territory.
Watch out: Data arriving through a webhook is input from the internet, even after authentication. Never interpolate it blindly into database queries, shell commands (Chapter 19), or prompts to AI models without considering what a malicious payload could do. Authentication tells you the caller knew a secret; it does not make the payload trustworthy.
Serious webhook providers — payment processors, source-control platforms, messaging services — sign their deliveries. Alongside the payload they send a header containing an HMAC (hash-based message authentication code): a cryptographic fingerprint computed from the exact bytes of the request body plus a secret that only you and the provider share. If you recompute the fingerprint on your side and it matches, you have proof the request genuinely came from the provider and was not altered in transit — a stronger guarantee than any password header, because the secret itself never travels with the request.
The verification pattern in n8n has three parts:
Raw Body so the node hands you the body as
the exact bytes received, rather than parsed JSON. This is not optional
pedantry: the signature was computed over the original bytes, and if you
re-serialize parsed JSON, field ordering and whitespace differences will
change the bytes and the fingerprints will never match.Two refinements separate adequate from excellent. First, when the provider includes a timestamp in the signed material, check that it is recent (they document the tolerance) — this defeats replay attacks, where an attacker captures one legitimate signed request and re-sends it later. Second, keep the signing secret in a credential or as an environment variable rather than pasted into the Code node, so it never leaks through a shared or exported workflow (Chapter 34 covers secrets discipline).
Verifying that deliveries are flowing at all is easier: nearly every provider's developer settings include a delivery log showing each attempt, the response code your endpoint returned, and — crucially — a redeliver button. That button is your best friend during development: trigger one real event, then replay it against your test URL as many times as you need instead of repeatedly creating real orders or tickets.
The n8n side is half the job; the other half happens inside the sending application. The location varies by product, but the pattern barely does: look for a Webhooks, Developer, API, or Notifications area in the app's settings, add a new webhook, and you will be asked for a URL, an event selection, and often a signing secret or custom headers.
A registration routine that avoids the classic traps:
Listen for test event in n8n, and trigger a real event in
the app (create a test record, send a test delivery — many apps have a
"send test" button right in the webhook settings).Also worth checking in the provider's settings: which events you subscribed to (subscribe narrowly — every event type you accept is payload variety you must handle), and the provider's retry policy, meaning how many times and on what schedule it re-sends deliveries your endpoint failed to acknowledge. Retries are a gift for reliability and a curse for duplicates; Chapter 24's idempotency patterns are the answer.
Tip: Some apps cannot send webhooks natively but can call a URL through their own automation or scripting features; and anything that can run a
curlcommand (the ubiquitous command-line tool for making HTTP requests) — a shell script, a cron job, another n8n instance — can call your webhook. The Webhook node is not only for official integrations; it is a universal inbox for anything that speaks HTTP. This is also the standard bridge from apps whose native integration n8n lacks (compare Chapter 12's catalog and Chapter 15's community nodes before building).
Not everything arrives as tidy JSON. The Webhook node copes with the common variations, but each needs a moment of understanding.
Form submissions often arrive as
application/x-www-form-urlencoded — the classic web-form
encoding — which n8n parses into body fields just like
JSON, so downstream nodes rarely notice the difference. File
uploads arrive as multipart/form-data, a container
format mixing text fields and files; n8n places the text fields in
body and the files into the item's binary section,
the separate compartment n8n uses for file data (Chapter 20 explains the
binary model and the options for naming the binary properties).
Raw and unusual bodies — XML, plain text, or anything
you need byte-exact — call for the raw body option you met in the
signature section, after which a transformation node can parse the text
however you like (Chapter 18). GET
requests carry no body at all; their payload is the query
string, which you read from query — a GET to
.../webhook/lookup?email=ada@example.com gives you
{{ $json.query.email }}.
If a sender claims one content type while sending another — it
happens — the parsed body comes out empty or mangled. The
debugging move is always the same: capture a delivery with the test URL,
open the input panel, and look at what actually arrived in
headers and body before assuming anything (the
fuller debugging craft is Chapter 22).
Everything above converges in the pattern that defines intermediate n8n work: webhook in, HTTP Request out. A webhook gives you an event the moment it happens; the HTTP Request node (Chapter 13) lets you act on it against any API on the internet. Together they connect any two systems that speak HTTP, whether or not n8n ships a node for either one.
Here is the pattern built end to end, as a concrete and reusable example: a signup-enrichment endpoint. Your product (or form tool, or billing system) fires a webhook when someone new signs up; the workflow verifies the sender, enriches the signup with data from an external API, writes the result to your CRM (customer relationship management system), and acknowledges — all in under a dozen nodes.
1. The front door. A Webhook node: method
POST, path new-signup, Header Auth credential
holding a shared secret, Respond set to Immediately. The
sender needs only an acknowledgment, and responding instantly means its
timeout and retry machinery never wakes up.
2. The bouncer. If the sender signs its deliveries, enable the raw body option and add the Code-node signature check from earlier, with the failure branch stopping cold. Because stage 1 already acknowledged the delivery, a rejected one is discarded silently rather than answered with an error status — acceptable for an event feed; if the sender must see rejections, use the Respond-node mode instead. If the sender only supports the header secret, the Webhook node's authentication already handled it and this stage disappears.
3. The tidy-up. A Set (Edit Fields) node maps the
sender's field names to yours: email from
{{ $json.body.email }}, name from
{{ $json.body.full_name }}, plan from
{{ $json.body.plan }}. Do this early, and everything
downstream works with your vocabulary instead of the sender's — when the
sender renames a field someday, you fix one node (Chapter 18 covers the
transformation toolkit).
4. The outbound call. An HTTP Request node calls an
enrichment API — any service that takes an email address and returns
company, role, and similar profile details. Method GET or
POST per the API's documentation, URL built with an
expression, the API key stored in a proper credential, never pasted into
the URL (Chapters 11 and 13). This is the "HTTP Request out" half: your
workflow is now a client of one API seconds after being a
server to another.
5. The guard rail. Enrichment APIs fail, rate-limit, and return empty results for unknown emails. Configure the HTTP Request node's error handling so a failure routes to a fallback branch rather than killing the run (Chapter 23 covers node-level error branches) — an unenriched lead in the CRM beats a lost lead every time. A Merge or If arrangement joins the enriched and fallback paths (Chapter 9).
6. The destination. Write the result to your CRM — a catalog node if one exists (Chapter 12), or a second HTTP Request node if not. Make the write idempotent: search for the email first and update rather than create, so a retried delivery cannot mint duplicate contacts (Chapter 24).
Activate, register the production URL with the sender, trigger a real signup, and watch the execution in the executions list. You have built a service: an authenticated endpoint that receives events, calls out across the internet, handles failure gracefully, and leaves an audit trail. Every integration you build from here is a variation on these six stages — different sender, different outbound API, same skeleton. (Chapter 36 builds a full production system on exactly this backbone.)
A webhook endpoint is a standing promise, and a few operational habits keep it honest.
Know your downtime story. When the workflow is deactivated or the instance is unreachable, deliveries fail at the sender. Providers with retry policies will re-send for a while — check how long, because that window is your recovery budget after an outage. For senders that never retry, a missed delivery is gone, which argues for a periodic reconciliation sweep: a scheduled workflow that asks the source system for recent records and back-fills anything the webhook missed (Chapter 24 treats this recovery pattern properly).
Watch the failure signal. Production webhook executions land in the executions list, and failed ones should page somebody or at least ping a channel — that is what error workflows are for (Chapter 23). The provider's delivery log is the complementary view: n8n shows what happened to requests that arrived; the provider shows requests that never got a response. When the two disagree, you have learned something important. Chapter 25 covers turning all this into ongoing monitoring.
Mind the volume. Each delivery is an execution, with everything that implies for storage of execution data (Chapter 21) and instance load. A chatty sender emitting hundreds of events a minute deserves narrower event subscriptions at the source, and on self-hosted instances, sustained heavy webhook traffic is precisely what queue mode and dedicated webhook processors exist for (Chapter 33).
Rotate and prune. Treat webhook secrets like any credential: rotate them on a schedule and when people leave. And when you retire a workflow, delete its registration in the sending app too — an orphaned registration hammering a dead URL pollutes the provider's delivery log and, worse, keeps a documented-but-forgotten door in your inventory.
Watch out: Deactivating a workflow "just for a minute" while editing takes its production URL offline; every delivery in that window fails. For hot endpoints, edit a duplicate and swap, or at minimum check the sender's retry window before you toggle. The executions list will show a gap, not an error — silence is the failure mode.
Webhooks are where n8n stops being a scheduler of chores and becomes infrastructure: systems you do not control now push their events into workflows you fully control, and workflows answer the internet like services. The next chapter (Chapter 15, Community Nodes and Building Your Own) covers what to do when even the catalog plus HTTP Request plus webhooks is not enough — extending the palette itself.
Sooner or later you will search the nodes panel for a tool your team depends on and come up empty. Maybe it is a niche accounting platform, a regional shipping carrier, an internal API your own developers built, or a brand-new SaaS product the catalog has not caught up with yet. Chapter 12 (Navigating and Operating the Integration Catalog) covered what ships in the box; this chapter covers what happens at the edge of the box. n8n has an extension ecosystem — community nodes — that lets anyone package up a new integration and share it, and it gives you the machinery to build one yourself. You do not need to become a programmer to get value from this chapter. The goal is that by the end you can install and vet third-party nodes responsibly, decide whether a custom node is worth building, and brief a developer well enough that the project succeeds on the first attempt.
A community node is an integration for n8n written by someone other than the n8n team, packaged so your instance can install it and treat it like any built-in node. Once installed, it appears in the nodes panel, has its own parameter fields and credential types, and participates in workflows exactly the way a native node does. Your teammates dragging it onto the canvas may never know it was not part of the core product.
Under the hood, a community node is an npm package. npm (originally
"Node Package Manager") is the standard public registry where JavaScript
software is published and shared — think of it as an app store for code
libraries, with millions of packages and no paid gatekeeping. Community
nodes follow a naming convention (package names beginning with
n8n-nodes-) and carry a special marker in their metadata so
n8n can recognize them. When you install one, your n8n instance
downloads the package from the registry and loads it into the running
application.
That last sentence deserves a beat of reflection. Installing a community node means running someone else's code inside your automation server — the same server that holds your credentials (Chapter 11, Credentials from Zero) and touches your business data. That is why n8n splits the ecosystem into two tiers, and why this chapter spends real time on vetting before it gets to the fun part.
The two tiers:
Verification is a meaningful signal, not a guarantee. A review happened at a point in time; packages get updated afterward. Treat "verified" as "screened," the way you would treat an app that made it into a curated app store — safer than a random download, still worth a look before you hand it your keys.
Your hosting model (see Chapter 2, The n8n Product Family and How It Is Sold) determines what you can install:
| Capability | n8n Cloud | Self-hosted |
|---|---|---|
| Verified community nodes | Yes — installable from the nodes panel by the instance owner or an admin | Yes — same in-panel experience, and the feature can be switched off by configuration |
| Unverified nodes from npm | No | Yes — but off by default in recent versions; an admin must first
enable it, then install by name from
Settings > Community Nodes |
| Manually installed or private packages | No | Yes — via the instance's filesystem or a custom container image |
| Who can install | Instance owner or admin | Users with the owner or admin role |
| Who can use an installed node | Any member of the workspace | Any user on the instance |
Two implications are worth calling out. First, if you are on Cloud
and the integration you need only exists as an unverified package, you
are stuck unless the author gets it verified, you switch to
self-hosting, or you fall back to the HTTP Request node (Chapter 13).
Check this before promising a stakeholder that "there's a node for it."
Second, on self-hosted instances, administrators govern the whole
ecosystem through environment variables — configuration switches set
where n8n runs. N8N_COMMUNITY_PACKAGES_ENABLED turns the
feature on or off entirely; N8N_UNVERIFIED_PACKAGES_ENABLED
decides whether truly unverified packages may be installed at all. Note
the default posture of recent n8n versions: verified nodes are allowed,
but unverified installs are blocked until an admin deliberately
turns them on. Chapter 32 (Self-Hosting from Zero) explains how
environment variables reach your instance; Chapter 34 (Access, Security,
and Secrets for Teams) covers the governance conversation about who
should hold the install privilege.
Watch out: A community node runs with the full privileges of your n8n process. It can read the data flowing through workflows that use it, make network calls to any destination, and — on self-hosted instances — potentially touch the server's filesystem and environment. There is no sandbox that limits a node to "just its own integration." Install accordingly.
On both Cloud and self-hosted instances, verified community nodes surface in the same place you find everything else: open the nodes panel (the search that appears when you add a node to the canvas) and type the product name. Matching verified community nodes appear in a community section of the results, visually distinguished from built-in nodes. If you are the instance owner or an admin, selecting one prompts you to confirm the install; after a short pause the node is available to everyone in the workspace. On Cloud, the owner can also hide or disable community nodes entirely from the Cloud admin panel.
For packages that have not been through verification, self-hosted
administrators install by exact package name. Go to
Settings > Community Nodes, choose the install option,
and enter the npm package name — for example
n8n-nodes-somevendor. n8n shows a risk acknowledgment you
must check before it proceeds; this is not boilerplate, it is the moment
the vetting checklist below is for. After installation the node appears
in the panel for all users, marked with an indicator so people know it
is third-party code.
There is a catch on current versions. Out of the box, recent n8n
releases refuse unverified installs — the box returns an error along the
lines of "installation of unverified community packages is forbidden" —
until an administrator has set
N8N_UNVERIFIED_PACKAGES_ENABLED=true (or pinned the
specific package's checksum) in the instance configuration. This is
deliberate friction, and a good thing: it forces the risk decision to
happen once, at the environment level, by whoever runs the server,
rather than silently in the UI. If your install route is blocked, that
env var — not a broken button — is usually why. Confirm your version's
default before promising a stakeholder this path will work.
You can find candidate packages by searching the npm website for the
n8n-nodes- prefix, browsing n8n's own integration directory
(community nodes are listed alongside native ones on the n8n website),
or following links from the community forum where authors announce their
work.
Tip: Always copy the package name from the author's official repository or npm page rather than typing it from memory. "Typosquatting" — publishing a malicious package under a near-identical name like
n8n-nodes-goggle-sheets— is a real attack pattern on public registries, and an exact-name install box is exactly where it bites.
Self-hosted operators can also install packages outside the UI, using
npm directly in the n8n user folder on the server (by convention, a
nodes directory inside the .n8n folder). This
is how you install a package from a private registry, a local file, or a
specific pinned version, and it is the route you will use for private
internal nodes later in this chapter. If you run n8n in Docker — the
container technology most self-hosted deployments use — the durable
version of this is building a small custom image that layers your
packages on top of the official one, so installs survive container
rebuilds. Your infrastructure person will recognize the pattern
immediately.
Community nodes do not update themselves. When a new version of an
installed package is published,
Settings > Community Nodes shows an update prompt next
to the package, and an administrator applies it deliberately. This is a
feature, not a chore: an update replaces running code, and a new version
can change a node's behavior, rename operations, or alter its output
shape in ways that break existing workflows.
Watch out: Treat a community node update like a small software deployment, because that is what it is. Read the changelog if the author publishes one, update on a test instance first if you have one (Chapter 10 discusses keeping environments tidy), and re-run your most important workflows that use the node before considering the update done. If a workflow silently starts producing malformed data after an update, Chapter 22 (The Debugging Craft) is your friend — but ten minutes of pre-checking is cheaper.
Uninstalling happens in the same
Settings > Community Nodes screen. The important
consequence: any workflow that uses a node from the removed package
breaks — the canvas shows the node as unrecognized, and executions fail
when they reach it. Before removing a package, search your workflows for
its nodes (the workflow list search and the executions log from Chapter
21 both help you find usage) and migrate or retire them first. The same
applies in reverse on restore and migration scenarios: if you move your
database to a fresh instance, community packages must be present there
too, and self-hosted deployments can set a startup option
(N8N_REINSTALL_MISSING_PACKAGES) that reinstalls missing
packages automatically so restored workflows do not wake up broken.
One more operational note for larger self-hosted deployments: if you run n8n in queue mode, where separate worker processes execute workflows (Chapter 33, Scaling and Performance), community packages need to be available to the workers as well as the main instance. Bake them into the shared image rather than assuming a UI install reaches every process.
Before the vetting checklist, it is worth being explicit about what you are actually risking, because "third-party code" is abstract until it is not.
A malicious or compromised community node could, in principle: exfiltrate the data of every item that passes through it; make requests to your other systems using whatever network access the n8n server has; or, in the worst self-hosted case, read files and environment variables on the host, which often include database passwords and the encryption key protecting your stored credentials. A merely sloppy node — far more common than a malicious one — can log sensitive payloads somewhere you did not expect, mishandle errors so failures pass silently, or fall out of maintenance and pin you to an old n8n version because it breaks on upgrade.
None of this is a reason to avoid the ecosystem. Thousands of teams run community nodes in production, the verified tier exists precisely to lower this risk, and the alternative — hand-building every niche integration — has costs too. It is a reason to treat installation as a decision someone accountable makes consciously, once, per package, rather than something any builder does casually on a Tuesday. Small teams: that accountable person is probably you. Larger teams: decide who holds the admin role and write down a lightweight policy — even three bullet points beats folklore.
Run through this before installing any unverified package, and skim it even for verified ones. None of it requires reading code fluently; it is the same due diligence you would apply to hiring a contractor.
Maintenance activity. On the package's npm page, check the last publish date and the version history. A package updated within the last few months, with a steady trickle of releases, signals a living project. A package untouched for a year or more may still work, but you are adopting unmaintained software, and n8n itself evolves underneath it.
Adoption. npm shows weekly download counts. High numbers do not prove safety (popular packages get compromised too), but very low numbers on an old package tell you almost nobody has road-tested it. Forum threads and GitHub stars on the source repository add texture: are real users reporting issues and getting answers?
Source availability and author identity. The npm page should link to a public source repository (usually GitHub). No linked source is close to disqualifying — you would be running code nobody can inspect. Look at the author: are they an established community member, the vendor of the service being integrated, or an anonymous account created last month?
Issue tracker health. Open the repository's issues list. A pile of unanswered "this broke after the latest n8n update" reports is a preview of your future.
Source inspection basics. Even without deep
JavaScript skills, you (or a developer you trust for thirty minutes) can
look for red flags: network requests to domains unrelated to the
integrated service; obfuscated or minified code in the source repository
where readable code should be; install-time scripts in the package
metadata (a postinstall script means code runs at install,
before you have used the node even once); and a surprisingly long list
of dependencies for a simple integration, since every dependency is
another link in the supply chain.
License. Confirm there is an open-source license your organization can live with. Most community nodes use permissive licenses; the absence of any license is a legal gray zone worth avoiding.
Tip: Keep a one-line register of every community package installed on your instance — name, version, why, who approved it, date. When a security question arrives ("do we run anything affected by X?") or an upgrade breaks, that list turns an afternoon of archaeology into a two-minute lookup. A pinned note or spreadsheet is fine; ceremony is not the point.
Now the other direction: the integration you need does not exist, and you want it to. This section is written so you can scope the work, decide whether to do it in-house or contract it, and brief a developer precisely — not to teach you TypeScript (the typed dialect of JavaScript that n8n nodes are written in). If you can read a config file, you can follow everything here.
A custom node is worth building when the same API will be used across many workflows or by many colleagues, when you want non-technical teammates to get friendly dropdowns and labeled fields instead of raw API mechanics, or when you plan to share the integration publicly. For one workflow and one builder, the HTTP Request node (Chapter 13) almost always wins on effort — hold that thought for the decision tree at the end.
n8n supports two ways of writing a node, and choosing between them is the single most important scoping decision, because it can swing the effort by several multiples.
A declarative-style node is mostly description, not logic. The author writes a structured definition — this node has these operations, each operation shows these fields, and each maps onto this HTTP request to the service's API — and n8n's engine does the actual requesting, looping over items, and error handling. Because there is little hand-written execution code, declarative nodes are faster to build, harder to get wrong, easier for n8n to review for verification, and more resilient across n8n version upgrades.
A programmatic-style node contains real executable code: an execute function the author writes, which receives the incoming items (the data units from Chapter 3 and Chapter 16) and can do anything JavaScript can do. This is the full-power option, and it is required whenever the integration is more than "make standard HTTP API calls and return the JSON": trigger nodes that listen for events (see Chapter 7 for what triggers are), services that do not speak conventional HTTP APIs, heavy data transformation inside the node, or intricate handling of binary files (Chapter 20).
| Question | If yes → | Style implied |
|---|---|---|
| Is the target a conventional REST API (the common web-API style from Chapter 13 — request in, JSON out)? | Declarative | Small project |
| Does the node need to trigger workflows on external events? | Programmatic | Medium project |
| Custom protocols, streaming, or heavy in-node computation? | Programmatic | Medium to large |
| Mostly standard operations plus one weird endpoint? | Declarative first; escalate only if blocked | Small, with a contingency |
When you brief a developer, say the words "declarative style unless you hit a wall, and tell me if you do." That one sentence prevents the most common overengineering failure, where a simple REST wrapper arrives three weeks late as a hand-rolled programmatic node.
n8n provides an official command-line tool — the
n8n-node CLI — that generates a complete, working node
project so nobody starts from a blank folder. A developer runs
npm create @n8n/node on their machine (which fetches and
runs that tool without a separate install), answers a few interactive
prompts (node name, which template — there are templates for declarative
HTTP-API nodes and for programmatic examples), and gets a ready-to-edit
project: the node definition, a matching credential definition, an icon
placeholder, the package metadata n8n requires, and preconfigured build
and lint tooling. n8n also maintains a starter repository
(n8n-nodes-starter on GitHub) that predates the tool and
works as a clone-and-edit alternative; the tool is the current
recommended path.
What is actually in the project, in operator terms: one file describes the node's interface (its name, icon, operations, and fields — everything users will see on the canvas), one file describes its credential type (which secret fields to collect and how to attach them to requests — the same machinery you met in Chapter 11), and the package metadata declares the whole thing as a community node package so instances know how to load it. A simple declarative node for a well-documented REST API is commonly a few days of developer time including testing and polish, not weeks. Triggers, OAuth flows (the redirect-based authorization dance from Chapter 11), and quirky APIs push estimates up; get a range from your developer after they have read the API docs, not before.
The scaffolding tool includes a development mode that compiles the node and launches a local n8n instance with the node already loaded — the developer opens the familiar editor in a browser, finds the new node in the panel, and exercises it in real workflows against the real API. Edit, save, retest, repeat. For projects not using the tool, the manual equivalent is linking the package into the n8n user folder's custom-extensions directory and restarting n8n.
As the operator, insist on seeing three things demonstrated before calling it done: the node handles multiple items in one execution correctly (the per-item behavior from Chapter 16 — a classic bug is processing only the first item); errors from the API surface as proper node errors that your error handling from Chapter 23 can catch, rather than vanishing; and the credential setup works from a clean slate, because the developer's machine has state a colleague's will not. n8n publishes an official linter ruleset for node packages — automated checks for common structural mistakes — and running it clean is a reasonable acceptance criterion to put in the brief.
Tip: Give your developer a one-page brief and the project will go dramatically better: a link to the target API's documentation, which authentication method the service uses, the five to ten operations users actually need (not the API's whole surface), a sample of real request and response payloads, and who will use the node (so they can judge how much hand-holding the field labels need). Most custom-node disappointments are briefing failures, not coding failures.
If the node should be shared — publicly, or across several instances
you run — it gets published to npm like any package. The n8n-specific
requirements are mechanical: the package name must carry the
n8n-nodes- prefix (or the scoped equivalent,
@yourcompany/n8n-nodes-…), the metadata must include the
community-node keyword and point at the built node and credential files,
and the scaffolded project has all of this wired already. Publishing
requires a free npm account; the standard npm publish
command does the rest. From that moment, any self-hosted instance that
permits unverified installs can add it by name.
Getting verified — and therefore installable on n8n Cloud —
is a separate, optional step: you submit the package to n8n through
their Creator Portal for review against published acceptance criteria.
The criteria evolve, but they consistently emphasize an open-source
license (n8n currently requires the permissive MIT license
specifically), minimal third-party dependencies, clean and consistent UX
text, documentation, and passing the official linter. The submission
process has also hardened over time — n8n now expects verified packages
to be published through an automated build pipeline that attaches a
provenance statement (cryptographic proof of who built the package and
from what source), so check the current submission requirements in n8n's
docs before you start rather than assuming a bare
npm publish will qualify. Review takes time and is at n8n's
discretion; if Cloud users matter to your plans (say, you are the vendor
of the service being integrated and want every n8n user to find you),
build to the criteria from day one — which mostly means preferring the
declarative style, keeping dependencies near zero, and licensing under
MIT.
Not everything belongs on a public registry. A node for your internal ERP or a proprietary partner API should stay private, and there are three clean patterns, in rough order of sophistication: install the package manually from a file or folder on the n8n server (fine for one instance and small teams); publish to a private npm registry — a registry only your organization can access, a standard facility in corporate development shops — and install by name as usual; or bake the package into your custom n8n Docker image so every environment and worker gets it automatically at deploy time. The third is the right answer for anyone running queue mode or multiple environments. Note that all three are self-hosted patterns: n8n Cloud has no mechanism for private nodes, which for some organizations is itself a deciding factor in the hosting choice discussed in Chapter 2 and Chapter 31.
You now hold four tools for the same gap. Here is the order to consider them in, and the questions that move you down the list.
Step 1 — Are you sure the catalog is actually out? Search the nodes panel for the product's parent company and product aliases, and check n8n's online integration directory. Chapter 12 covers catalog navigation; missing a node that exists under a different name is common.
Step 2 — HTTP Request node (Chapter 13). If the service has an HTTP API and this is one workflow's need, stop here. Zero installation, zero third-party code, works identically on Cloud and self-hosted, and credentials are handled with n8n's generic authentication types. The cost is that every builder touching it must think in API terms, and the same request logic gets copy-pasted if the need spreads. Rule of thumb: the first and second workflow that need an API justify HTTP Request; by the fifth, you are maintaining an accidental integration and should look further down this list.
Step 3 — Code node (Chapter 19). Choose this when the gap is not "talk to a service" but "compute something" — parsing an odd format, custom matching logic, a transformation the toolkit from Chapter 18 cannot express. The Code node can also make HTTP calls, but if HTTP is the point, prefer Step 2: it is more observable and more maintainable by non-coders.
Step 4 — Community node. If a package exists, weigh it with the vetting checklist. It wins when it is verified (or vets well), maintained, and the need spans multiple workflows or builders who benefit from a proper UI. It loses when the package is stale or opaque — a stale community node is usually worse than the HTTP Request node, because you inherit its bugs and its update risk while learning nothing about the underlying API.
Step 5 — Build your own. The last resort and sometimes the right one: no acceptable package exists, the need is durable and shared, and you have or can hire the developer time. Declarative unless proven otherwise; private unless sharing serves you; budget for maintenance, because APIs and n8n both keep moving after the launch party.
Two cross-cutting modifiers apply at every step. Hosting: on Cloud,
Steps 4 and 5 narrow to verified nodes only, which makes Steps 2 and 3
correspondingly more important. And AI usage: if the capability is
destined to become a tool for an AI agent (Chapter 28, The AI Agent
Node), know that community nodes can serve as agent tools on self-hosted
instances via an explicit configuration opt-in
(N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE) — one more
deliberate switch, for exactly the reasons this chapter has kept
insisting on.
Watch out: The decision tree is cheap to walk and expensive to skip. The failure mode to avoid is emotional, not technical: building a custom node because it sounds satisfying, when a twenty-minute HTTP Request configuration would have shipped the same outcome today. Extend the platform when the organization needs the extension — and when it does, you now know how to install it safely, vet it honestly, or brief the build precisely.