Webhooks & Push Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/src/webhooks/webhook.service.ts
- packages/cli/src/webhooks/tests/webhook.service.test.ts
- packages/cli/test/integration/webhooks.api.test.ts
- packages/core/src/execution-engine/node-execution-context/utils/tests/webhook-helper-functions.test.ts
- packages/cli/src/modules/oauth-server/tests/workflow-webhook-trigger-resource.resolver.api.test.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts
Webhooks serve as the primary entry point for event-driven workflows in n8n. The system provides a robust mechanism to register, resolve, and execute HTTP endpoints that trigger workflow executions. This system supports both static and dynamic path structures, multi-method listeners, and specialized handling for different content types.
Webhook Architecture
The webhook system operates through the WebhookService, which manages the lifecycle of webhook registrations in the database and provides high-performance lookup via a caching layer.
Core Components
| Component | Description |
|---|---|
| WebhookService | Central service for finding, storing, and managing webhook entities. |
| WebhookRepository | Data access layer for persisting webhook registrations. |
| WebhookContext | Provides the execution environment for webhook logic, including access to request data. |
| CacheService | Provides high-speed lookups for static webhooks to reduce database load. |
Sources: packages/cli/src/webhooks/webhook.service.ts:32-37, packages/cli/src/webhooks/webhook.service.ts:401-409
Webhook Resolution Flow
When an HTTP request arrives, the system follows a specific resolution order to find the correct trigger. It prioritizes exact static matches before evaluating dynamic templates.
Webhook Types
n8n distinguishes between static and dynamic webhooks based on their path structure.
Static Webhooks
Static webhooks use fixed paths like user/profile or a unique UUID. These are heavily cached for performance because their paths do not change.
Sources: packages/cli/src/webhooks/webhook.service.ts:60-64, packages/cli/src/webhooks/webhook.service.ts:94-98
Dynamic Webhooks
Dynamic webhooks include variable segments in their paths, denoted by colons (e.g., user/:id).
- Requirement: Dynamic webhooks must have a
<uuid>/base segment to ensure unique routing. - Matching Logic: The system picks the template with the most matching static segments. If a path is simply
:var, it acts as a catch-all for that segment count.
Sources: packages/cli/src/webhooks/webhook.service.ts:162-174, packages/cli/src/webhooks/webhook.service.ts:141-158
Execution and Response
The runWebhook function executes the logic defined within a node's webhook method. It creates a WebhookContext that allows the node to interact with the incoming request and provide a response.
Supported Content Types
The system automatically parses several common content types:
- JSON: Standard
application/jsonpayloads. - XML: Parsed into a JSON-like object structure.
- Form-urlencoded: Standard web form submissions.
- Multipart/form-data: Handles file uploads by creating temporary files on disk.
- Plain Text: Raw string data.
Sources: packages/cli/test/integration/webhooks.api.test.ts:143-188, packages/cli/src/webhooks/webhook.service.ts:401-419
Response Modes
Workflows can respond to webhooks in different ways:
- On Received: Returns a response immediately after receiving the request.
- Last Node: Returns the data from the final node in the workflow.
- Response Node: Uses a specialized
respondToWebhooknode to provide custom status codes, headers, and bodies (e.g., serving HTML).
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:7-13, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:31-33
Security and Authentication
Webhooks support multiple authentication methods, including Basic Auth, Header Auth, JWT, and n8n's internal OAuth2 implementation.
OAuth Protected Resources
Webhooks using n8nOAuth2 are registered as protected resources. The system resolves these resources using the path and HTTP method.
- Audience Scoping: Tokens are scoped per method. A token minted for a
GETtrigger will be rejected if replayed against aPOSTtrigger on the same path. - Disjoint Methods: n8n allows two different workflows to share a path if they use different HTTP methods. The resolution logic ensures that providing a
?method=selector correctly identifies the intended trigger.
Sources: packages/cli/src/modules/oauth-server/tests/workflow-webhook-trigger-resource.resolver.api.test.ts:133-149, packages/cli/src/modules/oauth-server/tests/workflow-webhook-trigger-resource.resolver.api.test.ts:175-188
Summary
The Webhooks system in n8n provides a high-performance, flexible entry point for workflows. By utilizing a tiered lookup strategy (Cache -> Static DB -> Dynamic Template DB), it maintains low latency for triggers while supporting complex URL patterns. The integration with the respondToWebhook node allows developers to build full applications, including SPAs, directly on top of the n8n webhook infrastructure.