# Webhook - Workflow trigger | Docs - nodulz

Source: https://nodulz.com/docs/nodes/webhook

Language: en

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:

1. Add this trigger and choose **POST** with a unique path, such as `/demo-request`.
2. In **Test payload**, enter `{ "email": "ada@example.test", "amount": 120 }`.
3. Connect an [Edit fields](/docs/nodes/set) node, enable **Mapped fields only** and add `email` with `{{ input.body.email }}` and `amount` with `{{ input.body.amount }}`.
4. 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": "ada@example.test", "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](/docs/nodes/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](/docs/credentials) 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

| Setting | Purpose and guidance |
| --- | --- |
| `method`<br>HTTP Method | HTTP verb used for the request (GET, POST, PUT, PATCH, DELETE). |
| `path`<br>Path | Path appended after /api/hooks (e.g. /orders → …/api/hooks/orders). Must be unique per trigger. |
| `multipart`<br>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`<br>Authentication | Verified before capture or execution. Republish the workflow after changes. Received authentication credentials are removed from workflow input. |
| `authUsername`<br>Basic username | Expected username without colons. The secret field contains the password. Send Authorization: Basic base64(username:password). |
| `jwtAlgorithm`<br>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`<br>JWT public key | SPKI public key in PEM format (BEGIN PUBLIC KEY). Do not paste a private key. |
| `jwtIssuer`<br>JWT issuer (optional) | When set, requires an exact match for the iss claim. |
| `jwtAudience`<br>JWT audience (optional) | When set, requires this audience in the aud claim. |
| `signatureHeader`<br>Signature header | Incoming header name. Empty: x-signature for HMAC, stripe-signature for Stripe. Case insensitive. |
| `signatureEncoding`<br>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`<br>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`<br>Respond | When to return the HTTP response to the caller. |
| `respondNodeKey`<br>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`<br>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`<br>Response node | Pick a downstream Webhook response node. Its JSON template is returned to the caller. |
| `respondNodeKey`<br>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.

```json
{
  "method": "POST",
  "path": "",
  "authentication": "none",
  "respond": "immediately",
  "responseFormat": "response_node",
  "responseTemplate": "{\n  \"data\": \"{{ nodes.http1.body.data }}\",\n  \"request\": \"{{ input.body }}\"\n}"
}
```

## Verification

Check the simulated payload first, then send a real request to the published URL. Find the execution and inspect its input and final status. If no execution appears, check method, URL, authentication and network access. Publish again after changing the trigger. A simulated test does not validate these incoming checks.

See also : [Expressions and data](/docs/expressions), [Executions](/docs/executions), [Node catalog](/docs/nodes).

## Explore further

- [Features - nodulz](https://nodulz.com/product/overview)
- [Node catalog - nodulz](https://nodulz.com/product/catalog)
- [MCP server - nodulz](https://nodulz.com/product/mcp)
- [Pricing - nodulz](https://nodulz.com/pricing)
- [Use cases and workflow automation - nodulz](https://nodulz.com/use-cases)
- [Choose what your workflows can do. - nodulz](https://nodulz.com/compare)
- [Documentation - nodulz](https://nodulz.com/docs)