n8n Webhook Node Explained: Test vs Production URLs, Auth, Responses and Debugging
By Abhishek Patoliya · 2026-08-11
The Webhook node is how most real-time n8n workflows start: another system sends an HTTP request to a URL that n8n owns, and the workflow runs with that request as its input. It is simple to add and easy to get subtly wrong. Most "my webhook doesn't fire" problems come from three things this lesson covers in detail: calling the test URL when the workflow is published (or the reverse), responding too late, and n8n generating the wrong public URL behind a reverse proxy.
By the end you will be able to configure the Webhook node deliberately, protect it, test it with curl, and debug it when a sender says the delivery failed.
Before you start: you should know what an HTTP request and a JSON body are. If not, read API Automation 101 and JSON, JSONPath and jq for automation builders first. You need an n8n instance you can reach; a local Docker install from the self-hosting guide works for everything except receiving calls from cloud services.
Product behaviour described here was checked against the n8n documentation on 8 November 2026. n8n changes quickly; the References section links to the pages to re-check.
What a webhook actually is
A webhook is an HTTP request that one system sends to another when an event happens. Instead of your workflow repeatedly asking a service "is there anything new?", the service calls you. The request has the same parts as any HTTP request:
- Method, usually
POST for events.
- URL: the address n8n gives you, optionally containing path parameters.
- Headers: content type, often a signature or token the sender adds.
- Query string:
?key=value pairs, common with GET.
- Body: the event data, usually JSON.
Webhook, polling or schedule?
| Trigger style | Latency | Cost when nothing happens | Use it when |
| Webhook | Seconds | None | The source system can send outgoing webhooks and you need to react to individual events. |
| Polling (a trigger that checks for new records) | Up to the polling interval | One request per interval | The source has no webhooks, or you can't expose a public URL. |
| Schedule | Fixed interval | One run per interval | Batch work: nightly syncs, reports. See Schedule Trigger vs cron. |
Test URL vs production URL
Every Webhook node has two URLs, shown at the top of the node panel. They behave differently, and mixing them up is the most common cause of a webhook that "works in the editor but not for real".
| Test URL | Production URL |
| Registered when | You click Listen for Test Event or Execute workflow (while the workflow isn't published) | You publish the workflow |
| Listens for | 120 seconds | Until the workflow is unpublished |
| Where you see the data | Directly in the editor, on the node | In the workflow's Executions list, not the canvas |
| Use it for | Building and debugging | Giving to the system that sends real events |
Two practical rules follow:
- Give the sending system the production URL, then publish the workflow. If you paste the test URL into Stripe or a form tool, deliveries will fail as soon as the 120-second listening window closes.
- Copy both URLs from the node panel rather than typing them. They differ by a path segment (the test URL contains
webhook-test), and n8n builds the host part from its configuration, which matters behind a proxy (see below).
Configuring the node
HTTP method
The node accepts DELETE, GET, HEAD, PATCH, POST and PUT. Pick the method the sender actually uses; a request with any other method won't match. To accept more than one, open the node's Settings, enable Allow Multiple HTTP Methods, then choose the methods in Parameters. The node then has one output per method.
Only one webhook can exist per path and method across your instance. If publishing fails with a conflict, another published workflow already uses that combination: change the path or unpublish the other workflow.
Path and path parameters
By default n8n generates a random path. Replace it with something readable, such as leads, and use :name segments for values carried in the URL, for example orders/:orderId/status. Supported shapes include /:variable, /path/:variable, /:variable/path and combinations with two variables. The values arrive in params (see "Where the data lands").
Authentication
The Authentication parameter offers:
- None: anyone who knows the URL can trigger the workflow.
- Basic auth: username and password in the
Authorization header.
- Header auth: n8n checks for a header name and value you define, for example
X-Api-Key. The simplest good option for your own apps and scripts.
- JWT auth: n8n verifies a JSON Web Token.
- n8n User Auth (OAuth2): requires the caller to be an authenticated n8n user; by default it also requires permission to execute the workflow (401 without a token, 403 without permission).
Third-party services (Stripe, GitHub, Shopify and others) usually can't send your custom header. They sign each request with a shared secret instead, and you verify the signature inside the workflow. That is covered step by step in n8n webhook signature verification.
When and how to respond
The sender waits for an HTTP response. The Respond parameter decides when n8n sends it:
| Respond option | What the caller receives | Choose it when |
| Immediately | A response as soon as the request arrives (body: Workflow got started), before any processing | Event notifications where the sender only needs an acknowledgement. The safest default for third-party webhooks. |
| When Last Node Finishes | The output of the last node, shaped by Response Data (All Entries, First Entry JSON, First Entry Binary, No Response Body) | Short workflows that return a result, and you accept the caller waiting for the whole run. |
| Using 'Respond to Webhook' Node | Whatever a Respond to Webhook node sends, wherever it sits in the workflow | You need control: different status codes for valid and invalid input, custom headers, or responding early and continuing work afterwards. |
| Streaming response | Data streamed as it is produced | Chat-style interfaces that display output progressively. |
Respond quickly. Senders treat a slow response as a failed delivery and usually retry, which can run your workflow twice. On n8n Cloud there is also a hard limit: if the webhook hasn't responded within 100 seconds, the request fails with a 524 error. For long jobs, respond immediately and do the work afterwards; if the caller needs the result, give it a second endpoint to poll or call it back when finished. The next lesson compares these response patterns in depth.
Options worth knowing
- IP(s) Allowlist: requests from other addresses get a 403. Useful when a provider publishes its sending IPs.
- Allowed Origins (CORS): defaults to
*. Restrict it if a browser page calls the webhook directly.
- Raw Body: keeps the body exactly as received. Signature verification needs this, because re-serialising parsed JSON changes the bytes.
- Binary Property: for file uploads, names the binary field the file is stored in.
- Ignore Bots: ignores requests from link previewers and crawlers.
- Response Headers and Response Content-Type: control the response when you don't use a Respond to Webhook node.
- Only Run If: a condition evaluated after the IP and authentication checks; requests that don't match get a 200 and no execution.
The maximum payload is 16 MB by default. On a self-hosted instance you can change it with the N8N_PAYLOAD_SIZE_MAX environment variable.
Worked example: a lead-capture endpoint
Goal: your website's backend sends new leads to n8n. The workflow rejects requests without an email address with a 400, accepts valid ones with a 201, and only then continues to your CRM. This is an illustrative build: substitute your own CRM step.
- Webhook node: method
POST, path leads, Authentication Header auth with a credential whose name is X-Api-Key and whose value is a long random string. Respond: Using 'Respond to Webhook' Node.
- IF node: condition
{{ $json.body.email }} is not empty.
- False branch → Respond to Webhook: Respond With JSON, Response Code
400, body {"error": "email is required"}.
- True branch → Respond to Webhook: Response Code
201, body {"status": "accepted"}. Then connect your CRM node after it, so the caller gets its answer before the slower CRM call runs.
Where the data lands
The Webhook node outputs one item whose JSON holds the request split into parts:
{
"headers": { "content-type": "application/json", "x-api-key": "…" },
"params": {},
"query": {},
"body": { "email": "ada@example.com", "name": "Ada" }
}
So downstream nodes read {{ $json.body.email }}, a query value with {{ $json.query.source }}, and a path parameter with {{ $json.params.orderId }}. A frequent mistake is writing {{ $json.email }}, which is empty because the field lives under body.
Testing it
Click Listen for Test Event, then within 120 seconds send a request to the test URL (copy it from the node; the host below is a placeholder):
curl -i -X POST "https://n8n.example.com/webhook-test/leads" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $LEADS_WEBHOOK_KEY" \
-d '{"email": "ada@example.com", "name": "Ada"}'
Expected: HTTP/1.1 201 and {"status":"accepted"}. Repeat without the email field and expect 400; repeat without the header and expect n8n to reject the request before the workflow runs. When all three behave, publish the workflow and switch the caller to the production URL. Keep the key in an environment variable as shown, never in source code.
Security checklist
- Authenticate every webhook that triggers anything meaningful. An unguessable path is not authentication: URLs leak through logs, browser history and shared screenshots.
- Verify signatures for third-party senders and reject old timestamps to stop replayed requests. See webhook security: signatures and replay protection.
- Validate the payload before using it: required fields, types, sizes. Treat it as untrusted input, especially before it reaches an LLM prompt, where injected text can change the model's behaviour.
- Make processing safe to repeat. Senders retry on timeouts and errors, so the same event can arrive twice. Deduplicate on the event ID before side effects: why webhook automations duplicate actions on retries shows how.
- Restrict by IP where the provider publishes its ranges, and restrict CORS for browser callers.
Self-hosting: public URLs behind a reverse proxy
n8n builds the webhook URLs it shows you from N8N_PROTOCOL, N8N_HOST and N8N_PORT. Behind a reverse proxy (n8n on port 5678, the proxy on 443 with TLS) that produces URLs the outside world can't reach. Set the public base URL explicitly:
N8N_WEBHOOK_URL=https://n8n.example.com/
N8N_PROXY_HOPS=1
According to the n8n documentation, N8N_WEBHOOK_URL replaces the older WEBHOOK_URL variable, which is deprecated from n8n 2.35.0 (n8n logs a warning if you still use it). N8N_PROXY_HOPS tells n8n how many proxies sit in front of it, so it reads the real client IP from X-Forwarded-For; without it, the IP allowlist sees the proxy's address and rejects legitimate callers. Make sure the last proxy forwards X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto.
Testing from cloud services against a laptop install needs a tunnel; Part 7 of the Run n8n locally with Docker series sets one up.
Troubleshooting
| Symptom | Likely cause | Fix |
| 404 / "webhook is not registered" | Calling the test URL while not listening, or the production URL while the workflow isn't published; wrong method | Use the URL that matches the state; check the method; publish the workflow |
| Works in the editor, nothing in production | The sender still has the test URL | Update the sender to the production URL; check the Executions list, not the canvas |
| Can't publish: path conflict | Another published workflow uses the same path and method | Change the path or unpublish the other workflow |
| Sender reports timeouts; 524 on n8n Cloud | Responding only after slow steps | Respond immediately or via an early Respond to Webhook node |
| Same event processed twice | Sender retried after a slow or failed response | Respond faster and deduplicate on the event ID |
| Expressions are empty | Reading $json.field instead of $json.body.field | Inspect the node output and use the right path |
| Allowlisted IPs get 403 | n8n sees the proxy's IP | Set N8N_PROXY_HOPS and forward X-Forwarded-For |
| URL shown in n8n uses localhost or port 5678 | Public URL not configured | Set N8N_WEBHOOK_URL |
For failures inside the workflow after the webhook fired, see n8n error handling and debugging a workflow that works manually but fails on trigger.
Key takeaways
- The test URL listens for 120 seconds after you click listen; the production URL works only while the workflow is published. Give senders the production URL.
- Incoming data is split into
headers, params, query and body.
- Respond fast, then work: slow responses cause retries, duplicates and, on n8n Cloud, 524 errors after 100 seconds.
- Authenticate, verify signatures for third parties, validate payloads and make processing idempotent.
- Self-hosted behind a proxy: set
N8N_WEBHOOK_URL and N8N_PROXY_HOPS.
Exercise: build the lead-capture endpoint above, then add a second path parameter version (leads/:source) and confirm the source arrives in $json.params.source. Next, continue to Respond to Webhook vs the Webhook node to turn this into a proper synchronous API.
References
Written by Abhishek Patoliya, Senior n8n Developer & Automation Architect, Surat, India. Verified n8n Creator.