Webhook Trigger Node

Start a workflow automatically when an HTTP request is received.

The Webhook Trigger node exposes a unique URL that, when called, starts a workflow run. The request is non-blocking — it returns immediately after the run is queued and does not wait for the workflow run to complete. The input field from the request body is passed as the output to the next node in the workflow. This makes it ideal for event-driven workflows triggered by external systems, form submissions, or other services that can send HTTP requests.

Parameters

This node has no configurable parameters. It is automatically configured when added to a workflow.

Webhook URL

Each workflow has a unique endpoint that accepts POST requests:

https://needle-ai.com/api/v1/workflows/<workflow-id>/runs

You can find this URL in the node's configuration panel when you select the Webhook Trigger in the workflow builder.

Authentication

All requests must include an x-api-key header with a valid Needle API key:

{
  "x-api-key": "<your-needle-api-key>",
  "Content-Type": "application/json"
}

Request Body

The request body must be JSON with the following structure:

Field	Type	Required	Description
runType	string	No	The run type. Use "test" for test runs or "production" to run the active published version of the workflow. Defaults to "production" if omitted.
input	object	No	Arbitrary JSON object passed as the trigger output to downstream nodes.

Example body:

{
  "runType": "production",
  "input": {
    "event": "new_order",
    "orderId": "ORD-12345",
    "customerEmail": "alice@example.com",
    "total": 99.99
  }
}

How It Works

1. When you add a Webhook Trigger to a workflow, Needle generates a unique webhook URL for that workflow.
2. Any HTTP POST request sent to that URL starts a new workflow run.
3. The input field from the request body is parsed and passed as the trigger output to downstream nodes.

Examples

1. cURL

curl -X POST "https://needle-ai.com/api/v1/workflows/<workflow-id>/runs" \
 -H "Content-Type: application/json" \
 -H "x-api-key: <your-needle-api-key>" \
 -d '{
  "runType": "test",
  "input": { "message": "Hello from cURL" }
}'

2. Trigger from an External System

An external system sends a POST request with order data:

Request body:

{
  "runType": "production",
  "input": {
    "event": "new_order",
    "orderId": "ORD-12345",
    "customerEmail": "alice@example.com",
    "total": 99.99
  }
}

Node output (available to downstream nodes):

{
  "event": "new_order",
  "orderId": "ORD-12345",
  "customerEmail": "alice@example.com",
  "total": 99.99
}

3. Trigger with an Array

{
  "runType": "production",
  "input": [
    { "id": 1, "status": "pending" },
    { "id": 2, "status": "pending" },
    { "id": 3, "status": "pending" }
  ]
}

Output Structure

The node outputs the value of the input field from the request body. The output format depends entirely on what the caller sends — typically a JSON object or array.

Important Notes

• Non-blocking: The webhook request returns immediately after the workflow run is queued. It does not wait for the workflow run to complete.
• HTTP method: The webhook only accepts POST requests.
• Content type: Send requests with Content-Type: application/json.
• Authentication: An x-api-key header with a valid Needle API key is required.
• No parameters: Unlike other trigger nodes, the Webhook Trigger has no configurable parameters — it simply passes through whatever data it receives in the input field.