Version: 2.6.4

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 custom authentication headers (or an explicit public mode for unauthenticated endpoints), optional IP allowlists, and a raw-body mode for signature verification (e.g., Stripe). The public endpoint is protected by a request-size cap and per-client rate limiting. 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. Custom Header Authentication Require one or more custom authentication headers (key-value pairs) for all webhook calls to prevent unauthorized access — or deliberately opt in to a public, unauthenticated endpoint.

3. Network Access Controls Restrict access by source IP/CIDR. A request-size cap and per-client rate limiting protect the public endpoint from abuse.

4. Structured Output with Metadata Pass request metadata (method, headers, query parameters, client IP) and the parsed body to downstream nodes for routing, filtering, and processing.

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: {CORE_API_URL}/scheduler/webhooks/{path}
- CORE_API_URL includes the API version prefix (e.g., http://localhost:8080/api/v1)
- Example: if CORE_API_URL = https://api.example.com/api/v1, the webhook URL becomes https://api.example.com/api/v1/scheduler/webhooks/{path}

Configuration Options

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

The webhook configuration is organized across six tabs in the UI: Basic, Authentication, Security, Response, Advanced, and Settings.

Parameter	Tab	Type	Default	Required	Constraints	Description
Enabled	Basic	boolean	`true`	Yes	--	Enable/disable the webhook. When disabled, requests to it are rejected.
Path	Basic	string	Auto-generated	Yes	`^[a-zA-Z0-9_-]+$`	URL path segment for the webhook endpoint.
HTTP Methods	Basic	string[]	`["POST"]`	Yes	GET, POST, PUT, PATCH, DELETE	HTTP methods accepted by the webhook.
Public Webhook	Authentication	boolean	`false`	No	--	When enabled (`allowUnauthenticated`), the webhook accepts requests with no authentication header — a deliberately public endpoint. When off (default), at least one auth header is required.
Auth Headers	Authentication	object	`{}`	Conditional	At least 1 non-empty key-value pair, unless Public Webhook is on	Custom authentication headers required in every request (exact key-value match).
IP Whitelist	Security	string[]	`[]`	No	Valid IPv4/IPv6 or CIDR notation	Restrict access to specific client IPs. Empty = allow all. See the note on client IP resolution below.
Success Status Code	Response	number	`200`	No	100--599	HTTP status code returned when a single pipeline fires. The UI is fixed at `200`; other values are set via the API/MCP.
Success Message	Response	string	`"Pipeline execution started"`	No	--	Response body message on success.
Include Request ID	Response	boolean	`true`	No	--	Include the unique request ID in the response.
Raw Body Mode	Advanced	boolean	`false`	No	--	Preserve the raw request body in `_metadata.raw_body` for signature verification.

Shared paths & fan-out

Multiple pipelines in the same organization can share one webhook path. A request fires every matching pipeline whose HTTP method, IP allowlist, and authentication checks it satisfies; the response lists which pipelines were triggered and which were skipped (with the reason). Paths are unique per organization and cannot be reused by a different organization.

Client IP resolution

The IP allowlist (and _metadata.remote_ip) match the IP that MaestroHub resolves as the client. By default only the direct TCP peer is trusted, and any inbound X-Forwarded-For header is ignored. If MaestroHub runs behind a reverse proxy or gateway, set the server-level http.trustedProxies config to your proxy's network — otherwise the allowlist matches the proxy's address and legitimate clients may be blocked. Only listed proxy ranges are trusted (loopback/link-local/private are not implicit).

Settings

Description

A free-text area for documenting the node's purpose and behavior. Notes entered here are saved with the pipeline and visible to all team members.

Execution Settings

Setting	Options	Default	Description
Timeout (seconds)	number	Pipeline default	Maximum execution time for this node (1--600). Leave empty for pipeline default.
Retry on Timeout	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry the node if it times out.
Retry on Fail	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry on failure. When Enabled, shows Advanced Retry Configuration.
On Error	Pipeline Default / Stop Pipeline / Continue Execution	Pipeline Default	Behavior when node fails after all retries.

Advanced Retry Configuration (visible when Retry on Fail = Enabled)

Field	Type	Default	Range	Description
Max Attempts	number	3	1--10	Maximum retry attempts.
Initial Delay (ms)	number	1000	100--30,000	Wait before first retry.
Max Delay (ms)	number	120000	1,000--300,000	Upper bound for backoff delay.
Multiplier	number	2.0	1.0--5.0	Exponential backoff multiplier.
Jitter Factor	number	0.1	0--0.5	Random jitter (+-percentage).

Output Data Structure

When a webhook fires, the trigger node produces a structured output with two top-level keys: _metadata and payload.

`_metadata` Object

Field	Type	Description
`type`	string	Always `"webhook_trigger"`.
`method`	string	HTTP method of the incoming request (e.g., `"POST"`).
`path`	string	Full request URL path (e.g., `"/api/v1/scheduler/webhooks/abc123"`).
`headers`	object	All request headers (first value per key).
`query`	object	Query string parameters (first value per key).
`remote_ip`	string	Client IP address.
`request_id`	string	Auto-generated UUID for traceability.
`raw_body`	string	(Only when Raw Body Mode is enabled) The original unparsed request body.

`payload` Object

The parsed request body. If the body is valid JSON it is parsed into an object. If it is not valid JSON, it is stored as {"raw": "<original string>"}. If no body is sent, this is an empty object {}.

Example Output

{
  "_metadata": {
    "type": "webhook_trigger",
    "method": "POST",
    "path": "/api/v1/scheduler/webhooks/abc123",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer my-secret-token",
      "User-Agent": "MyApp/1.0"
    },
    "query": {
      "source": "erp"
    },
    "remote_ip": "203.0.113.42",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "payload": {
    "orderId": "PO-9921",
    "status": "approved",
    "items": [
      { "sku": "WIDGET-A", "qty": 100 }
    ]
  }
}

Referencing in Downstream Nodes

Use expressions to access webhook data in subsequent nodes:

$trigger._metadata.method -- HTTP method
$trigger._metadata.headers.Authorization -- a specific request header
$trigger._metadata.query.source -- a query parameter
$trigger._metadata.request_id -- the auto-generated request ID
$trigger.payload.orderId -- a field from the parsed request body

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."

Auth Headers

At least one header with a non-empty key and non-empty value is required — unless Public Webhook (allowUnauthenticated) is enabled
Every configured header must have a non-empty name and value
Error: "At least one authentication header is required, or enable "Public webhook" to create a public endpoint"
This rule is enforced at every layer — the UI, the pipeline validator, and the runtime request handler — so a webhook created via the API/MCP with neither auth headers nor the public flag is rejected on save

IP Whitelist

Each entry must be a valid IPv4/IPv6 address or CIDR notation (IPv4/0-32, IPv6/0-128)
Error: "Invalid IP address or CIDR notation"

Success Status Code

If set, must be a number in 100–599
Error: "Invalid success status code: {value} (must be between 100 and 599)"

Calling the Webhook

Method: Any of the methods selected in the node configuration (default POST)
URL: {CORE_API_URL}/scheduler/webhooks/{path}
Headers: Include all configured authentication headers as-is (exact key-value match required). Not required when Public Webhook is enabled.
Body: Free-form (JSON recommended). If rawBodyMode is enabled, the raw body is preserved in _metadata.raw_body for signature verification. The request body is capped (default 1 MiB); larger bodies are rejected with 413 Payload Too Large.

Abuse protection

The public webhook endpoint applies a request-size cap and per-client rate limiting. Requests over the size cap return 413; a client that exceeds the rate limit receives 429 Too Many Requests. Both limits are server-level configuration.

Example curl Command

curl -X POST \
  https://api.example.com/api/v1/scheduler/webhooks/abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token" \
  -d '{
    "orderId": "PO-9921",
    "status": "approved",
    "items": [{"sku": "WIDGET-A", "qty": 100}]
  }'

Example Response

The response always reports which pipelines the request triggered. When a single pipeline fires, the response also mirrors that pipeline's configured Success Message and request ID for backward compatibility:

{
  "status": "triggered",
  "triggered": [
    {
      "pipeline_id": "pl_9f2c...",
      "pipeline_name": "Order Intake",
      "node_id": "node-1",
      "execution_id": "ex_5a1b..."
    }
  ],
  "message": "Pipeline execution started",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

When a path is shared by several pipelines (fan-out), triggered lists every pipeline that fired, and a skipped array lists any that matched the path but did not run, each with a reason (auth, ip, method, pipeline_disabled, maintenance, or error):

{
  "status": "triggered",
  "triggered": [
    { "pipeline_id": "pl_a...", "pipeline_name": "Order Intake", "node_id": "node-1", "execution_id": "ex_1..." }
  ],
  "skipped": [
    { "pipeline_id": "pl_b...", "pipeline_name": "Audit Log", "node_id": "node-1", "reason": "ip" }
  ],
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The request_id field is included when Include Request ID is enabled (default: on), and always when more than one pipeline fires. The message field carries the configured Success Message (single-pipeline only).

Status codes

Code	Meaning
200 OK	At least one pipeline fired (or matched but was skipped for a server-side reason such as a disabled pipeline).
401 Unauthorized	Authentication failed (missing/incorrect header, or no auth on a non-public webhook).
403 Forbidden	Client IP is not in the allowlist.
405 Method Not Allowed	HTTP method is not in the webhook's allowed methods.
404 Not Found	No webhook matches the path.
413 Payload Too Large	Request body exceeds the size cap.
429 Too Many Requests	Per-client rate limit exceeded.
500 Internal Server Error	Dispatch failed.

A custom Success Status Code (100–599), when set via the API, is honored only when exactly one pipeline fires; multi-pipeline fan-out always returns 200.

Usage Examples

IoT Device Telemetry Ingestion

Key configuration

Label: IoT Telemetry Receiver
Description: Receives sensor readings from edge gateways
Parameters: path iot-telemetry, methods POST, auth header X-Device-Key: gw-secret-2024
Security: IP whitelist 10.0.0.0/8 (factory network only)
Advanced: raw body mode off
Settings: retry enabled, on error stop

Downstream usage: $trigger.payload.temperature to read sensor value, $trigger._metadata.remote_ip to identify the gateway.

Third-Party Webhook Relay (Stripe)

Key configuration

Label: Stripe Payment Webhook
Description: Receives Stripe payment events with signature verification
Parameters: path stripe-payments, methods POST, auth header Stripe-Signature: whsec_...
Security: IP whitelist with Stripe IP ranges
Advanced: raw body mode on (required for Stripe-Signature HMAC verification)
Settings: retry enabled, on error stop

Downstream usage: $trigger._metadata.raw_body for signature verification, $trigger.payload.type to route by event type (e.g., payment_intent.succeeded).

Multi-Method REST API Gateway

Key configuration

Label: Order API Gateway
Description: Accepts GET (status check) and POST (new order) requests
Parameters: path orders, methods GET and POST, auth header X-API-Key: orders-secret
Security: IP whitelist scoped to the calling service's egress range
Settings: retry disabled, on error continue

Downstream usage: Branch on $trigger._metadata.method — route GET requests to a lookup node and POST requests to an order-creation flow.

note

For a webhook called directly from a browser (cross-origin), allow the calling origin in the server-level http.corsOrigins config. There is no per-webhook CORS setting — CORS is a browser-enforced, deployment-wide concern, so it is configured once for the whole instance.

CI/CD Pipeline Trigger

Key configuration

Label: GitHub Deploy Hook
Description: Triggers deployment pipeline on push to main
Parameters: path github-deploy, methods POST, auth header X-Hub-Signature-256: sha256=...
Advanced: raw body mode on (for GitHub signature verification)
Settings: retry enabled, on error stop

Downstream usage: $trigger.payload.ref to verify the branch, $trigger.payload.head_commit.message for commit info.

Best Practices

Authentication

Prefer an authentication header — a webhook with neither a header nor Public Webhook enabled is rejected by validation
Only enable Public Webhook when the caller genuinely cannot send a secret; pair it with an IP Whitelist to limit exposure, and treat anyone who knows the URL as able to trigger the pipeline
Use strong, random header values (e.g., X-Webhook-Secret: <random 64-char hex>)
Rotate secrets periodically and update both the sender and the webhook configuration
For services that sign payloads (Stripe, GitHub), enable Raw Body Mode and verify signatures in a downstream node

Security

Use IP Whitelist when the caller's IP range is known (e.g., cloud provider CIDR blocks, internal networks)
Keep the whitelist empty only when callers are behind unpredictable NAT or CDN IPs
Behind a reverse proxy? The allowlist matches the real client IP only when the server's http.trustedProxies config lists your proxy's network. Otherwise it matches the proxy's address and legitimate callers may be blocked — configure it, or expect to allowlist the proxy IP instead
Cross-origin browser access is governed by the deployment-wide http.corsOrigins config, not a per-webhook setting

Path Design

Use descriptive, stable paths (e.g., stripe-payments, iot-telemetry) rather than auto-generated ones
Paths are globally unique across pipelines — avoid collisions by including a service or domain prefix
Paths support alphanumeric characters, hyphens, and underscores only

Response

Keep the default Success Message or customize it to help callers confirm which pipeline was triggered
Enable Include Request ID to correlate webhook calls with pipeline executions in logs
When a path is shared by several pipelines, inspect the triggered and skipped arrays in the response to confirm which ones ran

Raw Body Mode

Enable only when you need the original request body for signature verification
When enabled, the raw body string is available at $trigger._metadata.raw_body
JSON parsing still occurs normally — raw body mode adds the original string alongside the parsed payload

Overview​

Core Functionality​

What It Does​

Endpoint Format​

Configuration Options​

Basic Information​

Parameters​

Settings​

Output Data Structure​

_metadata Object​

payload Object​

Example Output​

Referencing in Downstream Nodes​

Validation Rules​

Node Configuration Validation​

Calling the Webhook​

Example curl Command​

Example Response​

Usage Examples​

IoT Device Telemetry Ingestion​

Third-Party Webhook Relay (Stripe)​

Multi-Method REST API Gateway​

CI/CD Pipeline Trigger​

Best Practices​

Authentication​

Security​

Path Design​

Response​

Raw Body Mode​

Overview

Core Functionality

What It Does

Endpoint Format

Configuration Options

Basic Information

Parameters

Settings

Output Data Structure

`_metadata` Object

`payload` Object

Example Output

Referencing in Downstream Nodes

Validation Rules

Node Configuration Validation

Calling the Webhook

Example curl Command

Example Response

Usage Examples

IoT Device Telemetry Ingestion

Third-Party Webhook Relay (Stripe)

Multi-Method REST API Gateway

CI/CD Pipeline Trigger

Best Practices

Authentication

Security

Path Design

Response

Raw Body Mode