Webhook

Node catalog Triggers

On this page

Starts the workflow when an HTTP request hits the public webhook URL (shown above once published).

Usage and specifics

Publish the workflow to activate its URL. Match the configured HTTP method and authentication. Depending on the mode, the response is immediate, supplied by a node or streamed.

Technical type : webhook. Runtime : nodulz.

Guided example

To receive a request containing an email address:

Add this trigger and choose POST with a unique path, such as /demo-request.
In Test payload, enter { "email": "[email protected]", "amount": 120 }.
Connect an Edit fields node, enable Mapped fields only and add email with {{ input.body.email }} and amount with {{ input.body.amount }}.
Run from the editor. Preparation output should contain the address and the number 120.

To also simulate query parameters and headers, use a complete request envelope:

json

{
  "method": "POST",
  "headers": { "content-type": "application/json" },
  "query": { "source": "demo" },
  "body": { "email": "[email protected]", "amount": 120 }
}

Read {{ input.query.source }} to get demo. A simple test object is placed in input.body; an object containing envelope keys such as body, headers or query is interpreted as a complete request. Use the explicit envelope if your business data uses these names itself.

After the processing test, configure the required authentication, publish and copy the URL shown by the node. From your caller, send the same JSON body using POST, Content-Type: application/json and the selected authentication details. Do not reconstruct the URL from the editor address.

In immediate response mode, the caller’s response does not necessarily contain the final result. If the client needs a computed result, use a mode that waits for it, such as a configured Webhook response node selected as the response.

Credentials and prerequisites

This node defines no dedicated external credential. Remote sources or execution targets may still need their own access credentials.

See the credentials guide if a remote source or execution target requires access.

Parameters

Names below are technical keys. Defaults are not a ready-to-run configuration: complete fields required by your operation. Paths containing [] describe list items; some fields depend on the selected mode.

Parameter	Type	Default	Values / limits
`rateLimitEnabled`	`boolean`	-	-
`rateLimitMax`	`number`	-	-; > 0
`rateLimitWindowMs`	`number`	-	-; > 0
`allowedIps`	`array`	-	-; max 256
`blockedIps`	`array`	-	-; max 256
`method`	`enum`	`"POST"`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`path`	`string`	`""`	-
`authentication`	`enum`	`"none"`	`none`, `header`, `query`, `basic`, `bearer`, `jwt`, `hmac`, `stripe`
`authUsername`	`string`	`""`	-
`jwtAlgorithm`	`enum`	`"HS256"`	`HS256`, `RS256`
`jwtPublicKey`	`string`	`""`	-
`jwtIssuer`	`string`	`""`	-
`jwtAudience`	`string`	`""`	-
`signatureHeader`	`string`	`""`	-
`signatureEncoding`	`enum`	`"hex"`	`hex`, `base64`
`respond`	`enum`	`"immediately"`	`immediately`, `when_finished`, `streaming`, `when_last_node_finishes`, `when_node_finishes`, `with_template`
`responseFormat`	`enum`	`"response_node"`	`template`, `last_node`, `node_output`, `response_node`, `streaming`
`responseTemplate`	`string`	`"{\n \"data\": \"{{ nodes.http1.body.data }}\",\n \"request\": \"{{ input.body }}\"\n}"`	-
`respondNodeKey`	`string`	-	-
`secret`	`string`	-	-
`testPayload`	`string`	`""`	-
`multipart`	`boolean`	`false`	-

Configuration help

method HTTP Method: HTTP verb used for the request (GET, POST, PUT, PATCH, DELETE).
path Path: Path appended after /api/hooks (e.g. /orders → …/api/hooks/orders). Must be unique per trigger.
multipart Files: Accept a multipart/form-data body. Up to 50 files (25 MB each, 64 MB total) are exposed on input.files (name, MIME type, base64). Text fields stay in body. Publish the workflow again after enabling this.
authentication Authentication: Verified before capture or execution. Republish the workflow after changes. Received authentication credentials are removed from workflow input.
authUsername Basic username: Expected username without colons. The secret field contains the password. Send Authorization: Basic base64(username:password).
jwtAlgorithm JWT algorithm: HS256 uses the shared secret; RS256 uses a PEM public key. Bearer token with required exp; nbf is checked when present. Other algorithms are rejected.
jwtPublicKey JWT public key: SPKI public key in PEM format (BEGIN PUBLIC KEY). Do not paste a private key.
jwtIssuer JWT issuer (optional): When set, requires an exact match for the iss claim.
jwtAudience JWT audience (optional): When set, requires this audience in the aud claim.
signatureHeader Signature header: Incoming header name. Empty: x-signature for HMAC, stripe-signature for Stripe. Case insensitive.
signatureEncoding Signature encoding: HMAC-SHA256 of the raw body, encoded as hex or base64. Optional sha256= prefix. This mode has no replay protection; use Stripe for timestamped signatures.
testPayload Test payload: JSON used when running tests from the editor (Run button). Mocks the webhook body, headers, and query. Plain object = input.body. Full object with body, headers, query, method simulates the whole request.
respond Respond: When to return the HTTP response to the caller.
respondNodeKey Streaming node: Opens the HTTP response when the workflow starts and streams this node's text as it is produced (typically an AI node). Content-Type: text/plain.
responseTemplate Response template: JSON with JavaScript expressions: {{ Object.keys(input.body) }}, {{ nodes.http1.body.data.length }}, {{ nodes.set1.api_items[0].id }}. Each {{ … }} value is resolved from input, nodes.http1, nodes.set1, or vars.
respondNodeKey Response node: Pick a downstream Webhook response node. Its JSON template is returned to the caller.
respondNodeKey Response node: Returns this node's raw output.

Examples

Path: /orders-created
Payload available as input.body, input.headers, input.query
Auth header: x-nodulz-secret: your-secret
Response: JSON template combining input.body and nodes.http1.body.data

Initial configuration

Initial catalog configuration example, to adapt before running. Keep secrets in credentials.