Webhook trigger node

Webhook Trigger Node

Overview

The Webhook Trigger Node starts a pipeline execution when an HTTP request is received at a unique webhook URL. It supports API key authentication, optional IP allowlists, CORS controls, and a raw-body mode for signature verification (e.g., Stripe). Use it to connect external systems and SaaS apps to MaestroHub pipelines.

---

Core Functionality

What It Does

1. Event Ingestion via HTTP
Start pipelines from any system capable of sending HTTP requests to a secure URL.

2. Secure Authentication
Require MaestroHub API keys for all webhook calls to prevent unauthorized access.

3. Network and Origin Controls
Restrict access by source IP/CIDR and enable fine-grained CORS origins where needed.

4. Flexible Responses
Return configurable HTTP status codes and response payloads with optional request IDs for traceability.

5. Raw Body Preservation
Optionally preserve the exact raw request body to support third‑party signature verification flows.

---

Endpoint Format

• Node type: trigger.webhook
• Manual execution: Not supported (supportsExecution: false)
• URL format: {BASE}/webhook/{pipelineId}/{path}
  • BASE is derived from CORE_API_URL with any /api/v{n} suffix removed
  • Example: if CORE_API_URL = https://api.example.com/api/v1, webhook URL becomes https://api.example.com/webhook/{pipelineId}/{path}

---

Configuration Options

Parameters Tab

Parameters Configuration

Settings Tab

Settings Configuration

Basic Information

Field	Type	Description
Node Label	String (Required)	Display name for the node in your pipeline. Must be non‑empty (trimmed).
Description	String (Optional)	Explains how/why this webhook starts the workflow.

---

Parameters (Tabs)

Basic Tab

Parameter	Type	Default	Description
Enable Webhook (enabled)	Boolean	true	When disabled, all requests to this webhook are rejected.
Path (path)	String	Auto‑generated 8‑char value on first load	Optional custom path segment. Allowed: letters, numbers, -, _. Must match ^[a-zA-Z0-9_-]+$.
HTTP Methods (httpMethods)	String[] (GET, POST, PUT, PATCH, DELETE)	['POST']	Allowed HTTP methods for this webhook. At least one is required.

Authentication Tab

All webhooks require MaestroHub API Key authentication.

Parameter	Type	Default	Description
API Key (apiKeyId)	String (UUID)	–	Required. Select a valid API key to authenticate requests.

Request header to call this webhook:

Authorization: ApiKey <your-api-key>

Security Tab

Parameter	Type	Default	Description
IP Whitelist (ipWhitelist)	String[]	[]	Optional. If provided, only requests from listed IPs/CIDR ranges are allowed. Supports IPv4, simplified IPv6, and CIDR (IPv4 /0–/32, IPv6 /0–/128).
CORS Allowed Origins (corsAllowOrigins)	String[]	[]	Optional. If provided, enables CORS and restricts to these origins (each must be a valid absolute URL).

Response Tab

Parameter	Type	Default	Description
Success Status Code (successStatusCode)	Number	200	Returned when the request is accepted. Must be between 100 and 599. Options shown: 200 OK, 201 Created, 202 Accepted (recommended for async).
Success Message (successMessage)	String	Pipeline execution started	Included in response body upon acceptance.
Include Request ID (includeRequestId)	Boolean	true	Adds a unique request ID to the response body for traceability.

Advanced Tab

Parameter	Type	Default	Description
Raw Body Mode (rawBodyMode)	Boolean	false	Preserves the exact raw request body (useful for signature verification with providers like Stripe).
Request Timeout (s) (requestTimeout)	Number (0–300)	30	Maximum time to wait for request handling. 0 = no timeout.

Settings

Basic Settings

Setting	Options	Default	Recommendation
Retry on Fail	true / false	false	Keep disabled for trigger nodes.
Error Handling (onError)	Stop Pipeline / Continue	Stop Pipeline	Use "Stop Pipeline" for triggers.

Documentation Settings

Setting	Type	Default	Purpose
Notes	Text	Empty	Internal documentation and team communication.
Display Note in Pipeline	Boolean	false	Show notes on the pipeline canvas for quick reference.

---

Defaults

• enabled: true
• path: Auto‑generated 8‑char string on first load
• httpMethods: ['POST']
• apiKeyId: '' (must select one)
• ipWhitelist: []
• corsAllowOrigins: []
• successStatusCode: 200
• successMessage: Pipeline execution started
• includeRequestId: true
• rawBodyMode: false
• requestTimeout: 30
• settings.basic.retryOnFail: false
• settings.basic.onError: stopPipeline
• settings.documentation.notes: ''
• settings.documentation.displayNoteInPipeline: false

---

Validation Rules

Node Configuration Validation

Label Requirements

• Must not be empty
• Must not consist only of whitespace
• Error: "Node name is required."

HTTP Methods

• Must include at least one method
• Each value must be one of: GET, POST, PUT, PATCH, DELETE
• Errors: "At least one HTTP method must be specified"; "Invalid HTTP method: {value}"

Path

• If provided, must match ^[a-zA-Z0-9_-]+$
• Error: "Path must contain only alphanumeric characters, hyphens, and underscores."

API Key

• Required and must be a valid UUID
• Errors: "API key is required for webhook authentication"; "apiKeyId must be a valid UUID"

Success Status Code

• Integer between 100 and 599
• Error: "Invalid success status code: {code} (must be between 100 and 599)"

Request Timeout

• Number in 0–300 (where 0 = no timeout)
• Errors: "Request timeout cannot be negative"; "Request timeout cannot exceed 300 seconds"

IP Whitelist

• Each entry must be a valid IP or CIDR
• Error: "Invalid IP address or CIDR notation: {value}"

CORS Origins

• Each entry must be a valid absolute URL
• Error: "Invalid CORS origin URL: {value}"

---

Calling the Webhook

• Method: Any of the methods selected in the node configuration (default POST)
• URL: {BASE}/webhook/{pipelineId}/{path}
• Headers:
  • Authorization: ApiKey <your-api-key>
• Body:
  • Free‑form (JSON, form, etc.). If rawBodyMode is enabled, the raw body is preserved for signature verification.
• Response:
  • Status: As configured (e.g., 200/201/202)
  • Body: Includes message (from successMessage) and optionally requestId when includeRequestId is true