Webhooks & Triggers

Relevant source files

The following files were used as context for generating this wiki page:

• packages/nodes-base/nodes/Webhook/Webhook.node.ts
• packages/cli/src/webhooks/webhooks.controller.ts
• packages/cli/src/webhooks/webhook-request-handler.ts
• packages/cli/src/webhooks/waiting-webhooks.ts
• packages/nodes-base/AGENTS.md
• packages/cli/src/modules/mcp/tools/webhook-utils.ts
• packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json

Webhooks and Triggers are the primary mechanisms for initiating workflow executions in n8n. They serve as the entry points that allow workflows to be started by external HTTP requests, on a schedule, or in response to events from other services. The Webhook node, in particular, is a core component that turns an n8n workflow into a custom API endpoint, capable of receiving data and responding in various ways.

This document outlines the different types of trigger nodes, with a deep dive into the configuration and architecture of the Webhook node and its request handling process within the n8n backend. It covers the lifecycle of a webhook request from reception to workflow execution and response.

Trigger Node Types

n8n supports several types of trigger nodes, each designed for a different initiation scenario. The primary types are defined within the node development guidelines.

Trigger Type	Node Type Constant	Description	Example Node
Webhook	WEBHOOK_NODE_TYPE	Implements webhook and webhookMethods for handling HTTP requests. Creates a unique URL to trigger the workflow.	n8n-nodes-base.webhook
Polling	N/A	Implements a poll method and has polling: true in its description. Periodically checks for new data.	n8n-nodes-base.gmailTrigger
Generic	N/A	Implements a generic trigger function for custom event sources.	n8n-nodes-base.mqttTrigger
Schedule	SCHEDULE_TRIGGER_NODE_TYPE	Triggers the workflow based on a defined time or interval (Cron).	n8n-nodes-base.scheduleTrigger
Form	FORM_TRIGGER_NODE_TYPE	Triggers based on a form submission.	n8n-nodes-base.formTrigger
Chat	CHAT_TRIGGER_NODE_TYPE	Triggers based on an incoming chat message.	n8n-nodes-base.telegramTrigger

Sources: packages/nodes-base/AGENTS.md, packages/cli/src/modules/mcp/tools/webhook-utils.ts:10-14

The Webhook Node (n8n-nodes-base.webhook)

The Webhook node is a fundamental trigger that exposes a unique URL to start a workflow. It can be configured to handle different HTTP methods, authentication schemes, and response strategies.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.ts, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json

Configuration Parameters

The Webhook node has several key parameters that define its behavior.

Parameter	Type	Description
path	string	A unique path segment for the webhook URL. If not set, a unique ID is generated.
httpMethod	string	The HTTP method the webhook will respond to (e.g., GET, POST).
authentication	string	The authentication method to secure the endpoint.
responseMode	string	Defines how and when the webhook responds to the request.
responseData	string	Used with responseMode: 'lastNode' to specify which part of the last node's data to return.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.ts:114-233, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json:20-29

Authentication Methods

The Webhook node supports multiple authentication methods to secure the endpoint.

Method	Description
none	No authentication is required. The endpoint is public.
basicAuth	Requires standard HTTP Basic Authentication (username and password).
headerAuth	Requires a custom header with a specific name and secret value.
jwtAuth	Requires a JSON Web Token (JWT) for authentication, which can be validated using a secret or a PEM key.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.ts:145-177, packages/cli/src/modules/mcp/tools/webhook-utils.ts:223-247

Response Modes

The responseMode parameter dictates the webhook's response behavior.

The following diagram illustrates the logic for determining the response.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.ts:183-233, packages/cli/src/modules/mcp/tools/webhook-utils.ts:289-317

Webhook Request Handling Architecture

When an external service sends a request to an n8n webhook URL, the backend processes it through a series of components to trigger the correct workflow.

Sources: packages/cli/src/webhooks/webhooks.controller.ts, packages/cli/src/webhooks/webhook-request-handler.ts, packages/cli/src/webhooks/waiting-webhooks.ts

Request Lifecycle

The following sequence diagram illustrates the end-to-end flow of a webhook request.

Core Components

1. WebhooksController: This is the entry point for all webhook requests. It defines the API routes (/webhook, /webhook-test, /webhook-waiting) and delegates the processing to the WebhookRequestHandler. The controller handles both production and test webhooks.

   • POST /webhook/:workflowId/*: Endpoint for production webhooks.
   • POST /webhook-test/:workflowId/*: Endpoint for test webhooks executed from the editor.
   • POST /webhook-waiting/:workflowId/*: Endpoint for webhooks that use the responseNode mode.

   Sources: packages/cli/src/webhooks/webhooks.controller.ts:29-57

2. WebhookRequestHandler: This class contains the core logic for processing a webhook request. Its process method is responsible for:

   • Finding the workflow associated with the request.
   • Authenticating the request based on the webhook node's settings.
   • Determining the response mode.
   • Initiating the workflow execution via WorkflowExecute.
   • Handling immediate responses or registering the request with WaitingWebhooks if a later response is required.

   Sources: packages/cli/src/webhooks/webhook-request-handler.ts:59-106

3. WaitingWebhooks: This service manages webhooks that are configured to respond later in the workflow execution (i.e., responseMode: 'responseNode'). It holds the request and response objects in memory until a "Respond to Webhook" node is executed, at which point it sends the final response to the client.

   Sources: packages/cli/src/webhooks/waiting-webhooks.ts:25-53

Trigger Details for External Clients

n8n provides utility functions to generate human-readable details about a workflow's triggers. This is particularly useful for external systems, like an AI copilot, that need to understand how to interact with a workflow.

Sources: packages/cli/src/modules/mcp/tools/webhook-utils.ts

Details Generation Flow

The getTriggerDetails function orchestrates the collection of information about all supported trigger types in a workflow.

Sources: packages/cli/src/modules/mcp/tools/webhook-utils.ts:40-87

Webhook Credential Requirements

To help clients formulate a correct request, the system resolves and describes the authentication needed for a webhook.

Requirement Type	Description
none	No credentials are required.
basic	Requires Basic Authentication with a username and password.
header	Requires a specific HTTP header with a secret value. The header name is provided.
jwt	Requires a JWT. The variant specifies whether it's a secret or a pem-key.

Sources: packages/cli/src/modules/mcp/tools/webhook-utils.ts:19-22, 223-247

Conclusion

Triggers, and especially the Webhook node, are foundational to n8n's ability to integrate with the digital world. They provide a flexible and powerful way to start workflows from virtually any external event or on a defined schedule. The architecture is designed to be robust, supporting various authentication methods, response strategies, and clear programmatic introspection for advanced use cases like AI-driven workflow interaction. Understanding this system is key to building and debugging complex, event-driven automations in n8n.