Triggers
Relevant source files
The following files were used as context for generating this wiki page:
- packages/nodes-base/nodes/Webhook/Webhook.node.json
- packages/nodes-base/nodes/ManualTrigger/ManualTrigger.node.json
- packages/nodes-base/nodes/Github/GithubTrigger.node.json
- packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json
- packages/testing/playwright/tests/ui/5-ndv.spec.ts
- packages/nodes-base/nodes/Form/test/FormTriggerV2.node.test.ts
- packages/frontend/@n8n/i18n/src/locales/en.json
- packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts
- packages/nodes-base/nodes/Typeform/TypeformTrigger.node.json
- packages/nodes-base/nodes/SseTrigger/SseTrigger.node.json
Triggers are special nodes that start a workflow execution. They are the entry point for any automation, listening for specific events or conditions to occur before initiating the sequence of actions defined in the workflow. A workflow can have multiple triggers, allowing it to be started from various sources or events.
Triggers can be initiated manually by a user, scheduled to run at specific intervals, or activated by external events via webhooks. Each trigger node is designed to handle a specific type of event, such as a new message in Telegram, a form submission from Typeform, or a generic HTTP request to a Webhook URL. Once a trigger fires, it passes any relevant data from the event to the subsequent nodes in the workflow.
Sources: packages/frontend/@n8n/i18n/src/locales/en.json:1388-1390, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:10-11
Trigger Categories
Triggers in n8n can be broadly classified into several categories based on how they are initiated.
This diagram shows the main categories of triggers and some examples for each.
Sources: packages/nodes-base/nodes/ManualTrigger/ManualTrigger.node.json, packages/nodes-base/nodes/Webhook/Webhook.node.json, packages/nodes-base/nodes/Github/GithubTrigger.node.json, packages/nodes-base/nodes/SseTrigger/SseTrigger.node.json, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:200
Manual Triggers
These triggers require direct user interaction within the n8n editor to start a workflow. They are ideal for testing, debugging, or for tasks that need to be run on-demand.
- Manual Trigger: The most basic trigger, starts a workflow by clicking the "Execute workflow" button in the editor.
Sources: packages/nodes-base/nodes/ManualTrigger/ManualTrigger.node.json:2, packages/frontend/@n8n/i18n/src/locales/en.json:1400-1401
Webhook-based Triggers
These triggers listen for incoming HTTP requests to a specific URL. They are fundamental for creating APIs and integrating with external services that support webhooks.
- Webhook: A generic trigger that listens for any HTTP request (GET, POST, etc.) on a unique URL.
- Form Trigger: A specialized webhook that renders an HTML form at its URL and triggers the workflow upon form submission.
- SSE Trigger: Listens for Server-Sent Events.
Sources: packages/nodes-base/nodes/Webhook/Webhook.node.json:2, packages/nodes-base/nodes/Form/test/FormTriggerV2.node.test.ts:10, packages/nodes-base/nodes/SseTrigger/SseTrigger.node.json:2
Scheduled Triggers
These triggers execute workflows at predefined intervals.
- Schedule Trigger (also known as Cron): Runs a workflow at a specific time or on a recurring schedule (e.g., every hour, every Monday at 9 AM).
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:200, packages/frontend/@n8n/i18n/src/locales/en.json:1396-1397
App Event Triggers
These are specialized triggers that listen for events from specific third-party applications. They often use webhooks or polling behind the scenes but provide a simpler configuration experience tailored to the app.
| Application | Trigger Node | Description |
|---|---|---|
| Calendly | n8n-nodes-base.calendlyTrigger | Triggers on events like new invitee creation. |
| GitHub | n8n-nodes-base.githubTrigger | Triggers on repository events like push, pull request, etc. |
| Gmail | n8n-nodes-base.gmailTrigger | Triggers on new emails. |
| Mautic | n8n-nodes-base.mauticTrigger | Triggers on Mautic events. |
| Telegram | n8n-nodes-base.telegramTrigger | Triggers on new messages sent to a Telegram bot. |
| Typeform | n8n-nodes-base.typeformTrigger | Triggers when a Typeform is submitted. |
| Webflow | n8n-nodes-base.webflowTrigger | Triggers on Webflow site events. |
Sources: packages/nodes-base/nodes/Calendly/CalendlyTrigger.node.json:2, packages/nodes-base/nodes/Github/GithubTrigger.node.json:2, packages/nodes-base/nodes/Google/Gmail/GmailTrigger.node.json:2, packages/nodes-base/nodes/Mautic/MauticTrigger.node.json:2, packages/nodes-base/nodes/Telegram/TelegramTrigger.node.json:2, packages/nodes-base/nodes/Typeform/TypeformTrigger.node.json:2, packages/nodes-base/nodes/Webflow/WebflowTrigger.node.json:2
Webhook Trigger Execution Flow
Webhook-based triggers, such as the generic Webhook node and the Form Trigger, provide a URL that external systems can call. When a request is received, the workflow is executed.
The sequence diagram below illustrates the process for a test execution of a Webhook node.
This diagram shows the user initiating a test, the backend providing a URL, an external call being made to that URL, and the resulting data appearing in the editor.
Sources: packages/testing/playwright/tests/ui/5-ndv.spec.ts:40-50
Webhook URLs
Webhook triggers provide two URLs:
- Test URL: Used for triggering executions from the editor for testing and development. The results appear in the editor's output panel.
- Production URL: Used when the workflow is activated. These executions run in the background and their logs are available in the "Executions" list.
The URL path can be customized. If the path parameter is empty, a unique webhook ID (UUID) is used in the URL instead.
Sources: packages/testing/playwright/tests/ui/5-ndv.spec.ts:114-128, packages/frontend/@n8n/i18n/src/locales/en.json:1510-1511,1516
Form Trigger
The Form Trigger is a specialized webhook that renders an HTML form. It can be configured with various field types (text, number, select, file, etc.). When a user submits the form, the trigger fires, and the form data is passed into the workflow as JSON.
The test file for FormTriggerV2 demonstrates this by simulating a POST request with form data and verifying that the workflowData is correctly structured.
// Example from FormTriggerV2.node.test.ts
const bodyData = {
data: {
'field-0': 'John Doe',
'field-1': '30',
'field-2': '2024-08-31',
'field-4': '{}',
},
};
// ... test setup ...
expect(responseData).toEqual({
webhookResponse: { status: 200 },
workflowData: [
[
{
json: {
Name: 'John Doe',
Age: 30,
Date: '31 Jan',
Empty: null,
Tags: {},
submittedAt: expect.any(String),
formMode: 'test',
},
},
],
],
});
This snippet shows how submitted form data is converted into a structured JSON object within the workflow.
Sources: packages/nodes-base/nodes/Form/test/FormTriggerV2.node.test.ts:110-146
Trigger Node Definition
Each trigger is defined by a .json file that specifies its properties, categories, and documentation links.
A typical trigger node definition includes:
| Property | Description | Example Value |
|---|---|---|
node | The unique identifier for the node. | n8n-nodes-base.webhook |
nodeVersion | The version of the node. | 1.0 |
codexVersion | The version of the Codex system. | 1.0 |
categories | An array of categories the node belongs to. | ["Development", "Core Nodes"] |
resources | An object containing links to primary and credential documentation. | { "primaryDocumentation": [...] } |
subcategories | Defines where the node appears in the node creator panel. | { "Core Nodes": ["Other Trigger Nodes"] } |
Sources: packages/nodes-base/nodes/Webhook/Webhook.node.json:2-6, packages/nodes-base/nodes/SseTrigger/SseTrigger.node.json:16-18
The api_fundamentals.json tutorial workflow demonstrates how a ManualTrigger is used to start the tutorial, and multiple Webhook nodes are used to act as API endpoints, each with a unique path.
{
"id": "52e84ac4-6495-443e-b3d6-16d3291a6261",
"name": "Start Tutorial",
"type": "n8n-nodes-base.manualTrigger",
"position": [320, 464],
"parameters": {},
"typeVersion": 1
},
{
"id": "5aab442c-2fd7-4b41-ae0f-eeaf9e722213",
"name": "1. The Kitchen (GET /menu)",
"type": "n8n-nodes-base.webhook",
"position": [1632, 464],
"webhookId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"parameters": {
"path": "/tutorial/api/menu",
"responseMode": "lastNode"
},
"typeVersion": 2
}
This configuration shows a manualTrigger to begin the workflow and a webhook trigger configured to listen on the /tutorial/api/menu path.
Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json:9-29,39-53
Testing Triggers
Triggers are tested using both end-to-end (e2e) and unit tests.
E2E Testing
The Playwright test suite includes tests for the Node Detail View (NDV) that cover trigger functionality. For webhook-based triggers, the test involves:
- Adding the trigger node to the canvas.
- Opening the NDV and clicking the "Execute step" button.
- Retrieving the generated test webhook URL.
- Making an HTTP request to that URL.
- Asserting that the output panel in the NDV displays the data from the request.
// From 5-ndv.spec.ts
test('should test webhook node', async ({ n8n }) => {
await n8n.canvas.addNode('Webhook', { closeNDV: false });
await n8n.ndv.execute();
const webhookUrl = await n8n.ndv.getWebhookUrl();
await expect(n8n.ndv.getWebhookTriggerListening()).toBeVisible();
const response = await n8n.ndv.makeWebhookRequest(webhookUrl as string);
expect(response.status()).toBe(200);
await expect(n8n.ndv.outputPanel.get()).toBeVisible();
await expect(n8n.ndv.outputPanel.getDataContainer()).toBeVisible();
});
Sources: packages/testing/playwright/tests/ui/5-ndv.spec.ts:40-53
Unit Testing
Unit tests for triggers are written using Jest. These tests simulate incoming requests and verify that the trigger node correctly processes the data and produces the expected workflowData. The FormTriggerV2.node.test.ts file provides a clear example of how to test a trigger's response to different HTTP methods, body data, and configurations.
Sources: packages/nodes-base/nodes/Form/test/FormTriggerV2.node.test.ts
Summary
Triggers are the essential starting points for all n8n workflows. They provide a versatile mechanism to initiate automations, whether through manual intervention, a fixed schedule, or real-time events from external applications. The system supports a wide array of built-in triggers for popular services, as well as generic triggers like the Webhook and Schedule nodes, which offer the flexibility to integrate with almost any system. Proper configuration and understanding of each trigger type are key to building reliable and efficient workflows.