Webhook Node

The Webhook node is a trigger that starts a workflow when it receives an incoming HTTP request. It creates a unique URL endpoint that external services, forms, or scripts can call to push data into n8n.

Test vs Production URLs

Every Webhook node exposes two URLs:

URL Type	When Active	Format
Test URL	While the editor is open and you click "Listen for Test Event"	https://<host>/webhook-test/<path>
Production URL	While the workflow is saved and set to Active	https://<host>/webhook/<path>

Warning: Common mistake

External services must use the production URL. The test URL only works while you are actively testing in the editor. If your workflow is not triggering in production, verify that the calling service is configured with the production URL, not the test URL.

HTTP Methods

The node can be configured to accept one or more methods:

Method	Typical Use
GET	Simple pings, health checks, or passing data via query parameters
POST	Receiving JSON or form payloads (most common)
PUT	Full resource updates
PATCH	Partial updates
DELETE	Deletion signals
HEAD	Availability checks (no body)

Set the HTTP Method parameter to the method your calling service will use. You can select multiple methods if the same endpoint should accept different request types.

Authentication Options

Option	Description
None	The URL is open and accepts requests from any caller.
Basic Auth	Requires a username and password sent via the Authorization: Basic header. Configure in n8n credentials.
Header Auth	Requires a custom header (e.g., X-API-Key) with a specific value. Configure the header name and value in n8n credentials.
JWT Auth	Validates a JSON Web Token in the Authorization header.

Tip

For production webhooks exposed to the internet, always enable at least Header Auth. Open webhooks can be discovered and abused by bots.

Key Parameters

Parameter	Description
Path	The URL path segment after /webhook/. Defaults to a UUID; can be set to a human-readable value (e.g., incoming-orders).
Response Mode	Controls when the HTTP response is sent back to the caller.
Response Code	HTTP status code returned to the caller (default: 200).
Response Data	What to include in the response body.

Response Modes

Mode	Behavior
Immediately	Returns a response as soon as the webhook receives the request. The workflow continues executing in the background.
When Last Node Finishes	Waits for the entire workflow to complete, then returns the output of the last node as the response body.
Using 'Respond to Webhook' Node	Waits for a dedicated Respond to Webhook node placed anywhere in the workflow. Gives full control over response timing, status code, and body.

Incoming Data Structure

Data from the incoming request is available under these paths:

Path	Contents
{{ $json.body }}	Parsed JSON body (for POST/PUT/PATCH)
{{ $json.headers }}	Request headers as key-value pairs
{{ $json.query }}	Query string parameters (for GET requests or URL params)
{{ $json.params }}	URL path parameters if the path contains :param segments

Common Patterns

Receive JSON from an external API or service:

Webhook (POST) --> Code (transform) --> Google Sheets (Append)

Set HTTP Method to POST and Response Mode to Immediately. The calling service gets a fast 200 OK, and n8n processes the payload asynchronously.

Build a simple API endpoint:

Webhook (GET) --> PostgreSQL (Select) --> Respond to Webhook

Accept a GET request with query parameters, fetch data from a database, and return the result as JSON. Set Response Mode to Using 'Respond to Webhook' Node.

Validate and reject bad requests:

Webhook (POST) --> IF (validate) --> Respond to Webhook (200) / Respond to Webhook (400)

Check required fields in the body with an IF node. Return a 200 for valid requests and a 400 with an error message for invalid ones.

Tips and Gotchas

• Path collisions. If two active workflows use the same webhook path and method, only one will receive the request. Use unique paths or include the workflow purpose in the name (e.g., order-webhook, support-ticket-webhook).
• Binary data. To receive file uploads, enable the Raw Body option. The file data will be available as a binary property.
• CORS. By default, n8n does not set CORS headers. If a browser-based app needs to call your webhook, configure CORS via a reverse proxy or use the Response Headers option.
• Self-hosted webhook URL. Set the WEBHOOK_URL environment variable to your public-facing URL. Without this, n8n generates webhook URLs using localhost, which external services cannot reach.
• Large payloads. n8n has a default body size limit (typically 16 MB). For larger uploads, adjust the N8N_PAYLOAD_SIZE_MAX environment variable.

Common Errors

External service gets a 404 when calling the webhook URL. The workflow is not active (production URL only works when the workflow is toggled to Active), or the URL path is incorrect. Verify the path matches exactly, including case. Also check that WEBHOOK_URL is set correctly on self-hosted instances -- without it, n8n generates URLs using localhost.

Webhook receives the request but $json.body is empty or undefined. The calling service may not be sending a Content-Type: application/json header, so n8n does not parse the body as JSON. Confirm the caller sends the correct content type. If the caller sends form data, the body will be under $json.body as form fields rather than a parsed JSON object.

CORS error when calling the webhook from a browser-based application. By default, n8n does not set CORS headers. Configure CORS headers via your reverse proxy (Nginx, Caddy, Traefik) or use the Response Headers option in the Webhook node to add Access-Control-Allow-Origin and related headers manually.

See Also

• Webhooks Concept
• Triggers
• Webhook Mastery Tips
• GitHub Issues from Webhooks Guide