This guide covers the mechanics and the traps. For the wider tool, see What is n8n?; for the underlying concepts in plain language, APIs, webhooks and JSON for non-developers.
The idea in one paragraph
Polling is asking "anything new?" every five minutes. A webhook is the other system telling you the moment something happens. That inversion is why webhooks are the foundation of fast revenue systems: a form fill, a payment, a completed call or a CRM stage change can start work in seconds rather than at the next check. When people talk about speed to lead, a webhook is usually the first component.
Test URL vs production URL
This is the single biggest source of confusion, so let's be precise about what n8n's docs say.
- The test URL activates when you select Listen for test event, and incoming data is displayed in the editor so you can inspect it. The test webhook stays active for a limited window — n8n documents 120 seconds — after which you re-register it (Workflow development).
- The production URL is registered when the workflow is saved and published. Data arriving through it isn't visible in the editor; you inspect it in the Executions tab instead (Webhook node).
Two practical consequences:
- A 404 on your production URL usually means the workflow isn't published. Check that before you check anything else.
- Never leave a test URL in another system's configuration. It will work during the demo and stop working before lunch.
If you self-host n8n locally, the docs note you need tunnel mode for the Webhook node to be reachable from the internet (Workflow development).
Configuring the node
Methods. The Webhook node accepts DELETE, GET, HEAD, PATCH, POST and PUT. By default it registers one method; the docs describe an Allow Multiple HTTP Methods setting if you need more than one on the same path (Common issues).
Path and parameters. You set a custom path, and it supports variables in the route such as /:variable or /path/:variable (Webhook node). Useful for things like /lead/:branch.
One webhook per path and method. n8n only permits registering one webhook for each path-and-method combination; conflicts are resolved by changing the path or unpublishing the competing workflow (Common issues). Name paths deliberately — /inbound-lead-v2 beats /webhook1.
Files. A Binary Property option lets the node receive files on POST, PATCH and PUT (Webhook node).
Size. The documented maximum payload is 16MB, adjustable on self-hosted instances via N8N_PAYLOAD_SIZE_MAX (Webhook node).
Authentication: a URL is not a secret
The Webhook node offers four choices: Basic auth, Header auth, JWT auth or None. n8n's credential documentation describes header auth as a name-and-value pair, and the JWT credential as supporting either a passphrase or a PEM key as the key type (Webhook credentials).
How to choose:
| Situation | Use |
|---|---|
| Your own systems calling each other | Header auth with a long random value |
| A vendor that only supports username/password | Basic auth, over HTTPS |
| A partner that issues signed tokens | JWT auth |
| A public form with no secret possible | None — but validate hard and rate-limit upstream |
"None" is a legitimate choice for some public endpoints, and it is never a default choice. An unauthenticated webhook that writes to your CRM is an open write endpoint on the internet.
Responding: the decision that breaks systems
The Webhook node's Respond option has four documented modes (Webhook node):
- Immediately — returns a "Workflow got started" message.
- When Last Node Finishes — returns data from the final node executed.
- Using 'Respond to Webhook' Node — you control the response explicitly.
- Streaming response — streams data back, with compatible nodes.
The Respond to Webhook node requires the Webhook node's Respond setting to be "Using 'Respond to Webhook' node", and can respond with all incoming items, the first incoming item, custom JSON, text, a redirect, a binary file, or no data — with a configurable response code and response headers. It runs once, using the first incoming data item (Respond to Webhook).
The MitHub rule: answer the door, then do the work
Respond as early as the caller's contract allows. The caller — a form, a vendor, a payment processor — usually needs a fast acknowledgement, not your enrichment results. Holding the connection open while you call three APIs turns their retry logic into your outage.
There is a hard limit that makes this concrete: n8n's docs note that webhooks on n8n Cloud time out after 100 seconds because of a Cloudflare limit, and recommend a two-webhook pattern for long processes — one to start the work and respond immediately, another to report or poll for status (Common issues).
Respond late only when the caller genuinely needs the result in the same request: a lookup, a validation, a chatbot reply. Even then, keep the path short and put a workflow timeout on it.
The four questions every production webhook must answer
This is the checklist we use at MitHub before a webhook is allowed to touch anything real.
1. Who is calling?
Authentication set, and the caller identified in the payload (source: "website-form"). If you can't tell two callers apart, you can't debug either of them.
2. What does this payload mean?
Write the expected shape down — field names, types, which are required. Then validate at the top of the workflow and fail loudly on anything malformed, rather than letting empty strings travel through ten nodes. The error handling guide covers the deliberate-failure pattern.
3. What do I return, and how fast?
Chosen response mode, chosen status code, and a documented answer to "what does the caller do if we return an error?"
4. What happens if it arrives twice?
Assume every webhook will be delivered more than once, because well-behaved senders retry when they don't get a fast 200. Make the workflow idempotent: key on an ID from the payload, check whether you've already processed it, and update instead of duplicating. This is the same discipline described in the n8n and Clay integration guide.
A security checklist
- HTTPS only. No exceptions, including internal callers.
- Authentication on every endpoint that writes, spends or contacts a human.
- Validate before you act. Type-check the fields you'll use; reject the rest.
- Don't echo the payload back in the response. Reflecting input leaks data and invites abuse.
- Rotate the secret when someone with access leaves.
- Restrict by IP where the sender supports it. If you're behind a reverse proxy and IP checks misbehave, n8n documents the
N8N_PROXY_HOPSenvironment variable for exactly this (Common issues). - Log who called, when, and with what ID — not the full payload if it contains personal data.
- Have a kill switch. Know how to unpublish the workflow and where the traffic goes when you do.
Debugging, in order
| Symptom | First thing to check |
|---|---|
| 404 | Workflow published? Production URL, not test? Path typo? |
| 401 / 403 | Auth type matches what the sender is actually sending |
| Works in editor, not in production | You're testing the test URL; production data appears in Executions |
| Caller times out | Respond mode is waiting for the whole workflow; on Cloud, remember the 100-second ceiling |
| Duplicate records | No idempotency key; the sender retried after a slow response |
| Payload rejected | Size above the documented 16MB limit, or wrong content type |
| Another workflow "stole" the events | Two published workflows sharing a path and method |
Build one properly, once
Take a real trigger you care about — a form fill, a booking, a completed call — and build this skeleton:
- Webhook (POST, header auth, respond immediately).
- Validate required fields; Stop And Error if missing.
- Dedupe on an ID from the payload.
- Write the record first, with a status.
- Do the work — enrich, route, notify.
- Log the outcome, and link an error workflow.
That skeleton handles the overwhelming majority of revenue automations, and every one of its six steps exists because of a failure someone else already had. Building it for a real process, and then breaking it on purpose, is exactly the kind of proof of work the Faculty of Revenue Reverse Engineering asks you to produce.