n8n Webhook node: the complete reference

The n8n Webhook node is a trigger that gives your workflow an HTTP endpoint. Anything that can send an HTTP request (Stripe, GitHub, a form, your own backend) can start the workflow, and the workflow can answer like an API. This reference covers URLs, paths, authentication, the request data you receive, response modes, every option, and the errors that come up most.

Migrating a Pipedream HTTP trigger? The cutover plan for Pipedream HTTP triggers covers switching senders without losing events. This page is about the node itself.

Test URL and production URL

Each Webhook node has two URLs, shown at the top of the node panel (docs):

	Test URL	Production URL
Path prefix	/webhook-test/	/webhook/
Registered when	You select Listen for test event (or execute the workflow)	You publish the workflow
Listens for	120 seconds	Until you unpublish
Data shown in editor	Yes	No, see the Executions tab

A typical production URL is https://your-n8n.example.com/webhook/orders. On self-hosted n8n the webhook, webhook-test and webhook-waiting prefixes can be changed with N8N_ENDPOINT_WEBHOOK, N8N_ENDPOINT_WEBHOOK_TEST and N8N_ENDPOINT_WEBHOOK_WAIT (endpoint variables).

Most "webhook not working" reports come down to this table: the sender is configured with the test URL, or the workflow was never published.

Path and route parameters

By default the Path is a random UUID, which avoids collisions between workflows. Set your own path when you want a stable, readable endpoint. Route parameters are allowed:

/orders/:orderId
/:tenant/events
/:tenant/orders/:orderId

The values arrive in params, for example $json.params.orderId. n8n allows only one webhook per path and HTTP method across the instance; publishing a second one with the same pair fails until you change one of them.

HTTP methods

DELETE, GET, HEAD, PATCH, POST and PUT. By default a node accepts one method. To accept several, open Settings and turn on Allow Multiple HTTP Methods. The node then has one output per method, so a GET and a POST to the same path can take different branches.

What the workflow receives

The Webhook node outputs one item that includes these parts (plus metadata such as the webhook URL):

{
  "headers": { "content-type": "application/json", "x-signature": "..." },
  "params": { "orderId": "1042" },
  "query": { "dryRun": "true" },
  "body": { "id": 1042, "total": 59.9 }
}

Reference them downstream as {{ $json.body.total }}, or from later nodes as {{ $('Webhook').first().json.body.total }}. Query values are strings; convert before comparing numbers.

Payload limit: 16 MB. Self-hosted instances can change it with N8N_PAYLOAD_SIZE_MAX (in MiB). File uploads via form-data have their own limit, N8N_FORMDATA_FILE_SIZE_MAX.

To receive files, add the Binary Property option (POST, PATCH or PUT): the file lands in the binary field you name. To receive data in a raw format such as JSON or XML instead of parsed fields, turn on Raw Body.

Authentication

Method	Sender must send	Typical use
None	Nothing	Public forms, senders that sign payloads instead
Basic auth	Authorization: Basic …	Simple internal callers
Header auth	A header you define, e.g. X-API-Key: …	Most server-to-server calls
JWT auth	A signed JWT	Callers that already issue JWTs

The credential is stored like any other n8n credential. On top of auth you can add IP(s) Allowlist: requests from other IPs get a 403. Behind a reverse proxy, set N8N_PROXY_HOPS or the allowlist will see the proxy's IP.

Services like Stripe and GitHub sign the payload rather than sending a shared header. For those, keep Authentication on None and verify the signature first, either with the service's own n8n trigger node where one exists or with the Crypto node. Signature code in a Code node needs crypto, which is blocked in internal runner mode and must be allow-listed (NODE_FUNCTION_ALLOW_BUILTIN=crypto) on self-hosted runners.

Response modes

The Respond parameter decides what the caller gets back:

Respond	Caller receives	Use when
Immediately	Response code and "Workflow got started"	Fire-and-forget events, slow workflows
When Last Node Finishes	Output of the last node (All Entries, First Entry JSON, First Entry Binary, or No Response Body)	Simple API endpoints
Using 'Respond to Webhook' Node	Whatever the Respond to Webhook node defines	Custom status codes, headers, early replies
Streaming response	Streamed output	AI agent workflows with streaming nodes

On n8n Cloud, requests that don't get a response within 100 seconds fail with a Cloudflare 524 (common issues). For anything that may run longer, respond immediately and let the caller poll a second webhook for the result.

Options

Option	What it does
Allowed Origins (CORS)	Comma-separated origins; * by default
Binary Property	Store an uploaded file under this binary field
Ignore Bots	Skip link previewers and crawlers
IP(s) Allowlist	Allowed caller IPs, others get 403
Only Run If	Expression on { body, headers, params, query }; non-matching requests get a 200 without creating an execution
Raw Body	Keep the raw request body
Response Code / Headers / Content-Type / Data	Shape the response (availability depends on Respond mode)
Property Name	Return one key of the first entry instead of the whole object

Only Run If is handy for webhook senders that post many event types to one URL: {{ $json.body.type === 'invoice.paid' }} ignores everything else without creating executions.

HTML responses are wrapped in a sandboxed iframe since n8n 1.103.0, so relative form actions and scripts that touch the top window won't work.

Testing with curl

curl -X POST https://your-n8n.example.com/webhook-test/orders \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: test-key' \
  -d '{"id":1042,"total":59.9}'

Select Listen for test event first, then run the command within 120 seconds. Switch to /webhook/ once the workflow is published.

Common errors

Symptom	Cause	Fix
404 on the production URL	Workflow not published	Publish it
404 on the test URL	Not listening	Select Listen for test event, call within 120 s
Message that the path and method are already in use	Another published workflow has the same path and method	Change the path or unpublish the other workflow
403 from allowed IPs	n8n is behind a proxy	Set N8N_PROXY_HOPS
524 on Cloud	Response took longer than 100 s	Respond immediately, process async
Large requests rejected	Over the 16 MB payload limit	Raise N8N_PAYLOAD_SIZE_MAX (self-hosted) or send a link instead

From Pipedream HTTP triggers

A Pipedream HTTP trigger gives each workflow a URL on *.m.pipedream.net with a 512 KB body limit by default and returns a 200 "Success!" page unless you call $.respond() (Pipedream triggers). In n8n the same workflow starts with a Webhook node, and $.respond() becomes a Respond to Webhook node. Every sender has to be updated with the new URL, so plan the switch before Pipedream Workflows stops on March 31, 2027.

Our converter creates the Webhook node with the right method and response mode for each HTTP-triggered workflow and lists the URLs you need to change. The report and 1 workflow are free. Full export: $3 per workflow, $19 minimum — coming soon. Full process: migrate Pipedream to n8n.

Not affiliated with Pipedream or n8n.