Triggers, Webhooks & Polling
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/nodes-base/AGENTS.md
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
- packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
- packages/cli/src/modules/instance-ai/eval/workflow-analysis.ts
Triggers initiate the execution of n8n workflows by responding to external events, scheduled intervals, or manual user actions. They act as the entry point for all data processing, providing the initial payload that flows through downstream nodes. Triggers are categorized primarily into webhook-based, polling-based, and scheduled types, each implementing specific interfaces within the n8n execution engine.
Sources: packages/nodes-base/AGENTS.md:14-18, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:167-184
Trigger Architecture
Every trigger node implements the INodeType interface. Depending on the trigger mechanism, nodes implement specific functions that the n8n core invokes to start a workflow.
Trigger Types and Interfaces
| Trigger Category | Core Implementation | Interface/Method |
|---|---|---|
| Webhook | External systems call an HTTP endpoint. | webhook(), webhookMethods |
| Polling | Regularly checks an external service for new data. | poll(), polling: true |
| Schedule | Executes at specific times or intervals (cron). | n8n-nodes-base.scheduleTrigger |
| Generic | Custom logic to watch for events. | trigger() |
| Manual | Started by the user for testing. | n8n-nodes-base.manualTrigger |
Sources: packages/nodes-base/AGENTS.md:14-22, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:327-333
The following diagram illustrates the relationship between external events and the internal trigger methods used to start workflow execution.
The diagram shows how different input sources map to specific internal trigger mechanisms to begin workflow execution.
Sources: packages/nodes-base/AGENTS.md:14-22, packages/cli/src/modules/instance-ai/eval/workflow-analysis.ts:503-515
Webhook Triggers
Webhook triggers provide a public URL that external services call via HTTP methods (POST, GET, etc.).
Webhook Lifecycle
Nodes implementing webhooks often require a lifecycle to register and deregister endpoints with external services. The webhookMethods object contains:
checkExists: Verifies if the webhook is already registered.create: Registers the webhook with the external service.delete: Removes the registration when the workflow is deactivated.
Sources: packages/nodes-base/AGENTS.md:14-16, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:50-53
Webhook Response Modes
Webhooks can operate in different response modes:
- Default: Responds immediately with a generic confirmation (e.g., 200 OK).
- responseNode: The workflow continues and uses a
respondToWebhooknode to send a custom HTTP response (e.g., HTML for web apps).
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:3-13, packages/cli/src/modules/instance-ai/eval/workflow-analysis.ts:508-509
Polling Triggers
Polling triggers check for updates at defined intervals. This is used for services that do not support webhooks.
Polling Implementation
- Configuration: The node description must set
polling: true. - Logic: The
poll()function implements the check. - State Persistence: To avoid processing the same item multiple times, polling triggers use
getWorkflowStaticData('node')to store the ID of the last processed item or a timestamp.
Sources: packages/nodes-base/AGENTS.md:17-18, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:193-197
Data Output & Multi-Item Handling
When a trigger activates, it outputs data in the standard n8n item format.
Item Cardinality
If a trigger returns multiple items (e.g., a polling trigger finding 10 new emails), every downstream node executes once per item by default.
- Independent Sources: If Source A returns N items and chains directly into Source B, Source B runs N times.
- Execution Control: Setting
executeOnce: trueon a downstream node prevents it from running multiple times for the same trigger execution.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:46-51, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:34-37
The following sequence diagram shows the item flow from a multi-item trigger.
The diagram represents how n8n iterates over multiple items returned by a single trigger firing.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:34-37
Binary Data in Triggers
Triggers often carry binary data, such as file attachments from emails or form uploads.
Binary Handling Best Practices
- Gmail Trigger: You must set
SimplifytoFALSEandDownload AttachmentstoTRUEto access files. - MIME Types: Trigger metadata defines the
contentTypeandfilenamefor binary attachments. - Referencing: Binary data is accessed via
$binary.<property_name>. The property name depends on the node (e.g.,attachment_0for Gmail,datafor Webhooks).
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:41-47, 137-147, packages/cli/src/modules/instance-ai/eval/workflow-analysis.ts:241-260
Comparison of Trigger Mechanisms
| Feature | Webhook | Polling | Schedule |
|---|---|---|---|
| Real-time | Yes | No (delayed by interval) | No |
| Resource Usage | Passive (event-driven) | Active (constant checks) | Low |
| External Req. | Needs public URL | Needs API Read access | None |
| Example Node | n8n-nodes-base.webhook | n8n-nodes-base.gmailTrigger | n8n-nodes-base.scheduleTrigger |
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:167-184, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:11-14
Summary
Triggers define the entry point of every n8n workflow. Webhooks allow external systems to push data instantly, while polling allows n8n to pull data from systems that lack push capabilities. Manual and Schedule triggers facilitate testing and recurring tasks. Effective workflow design requires understanding how these triggers handle item counts and binary data to ensure efficient downstream processing.