HTTP Trigger

Serves HTTP endpoints and starts the workflow with the request. One method+path by default — or add ROUTES (GET /users/{id} → its own output port) to serve a whole API from one trigger, with pathParams extracted and anything unclaimed leaving on the unmatched port.

Finding it in the library

Search the builder's node library for HTTP Trigger (it lives under Input). A single click opens the in-editor docs panel shown here — description, ports, and every property, without leaving the canvas. Double-click (or drag) to add it to the workflow.

Wired up in the builder

HTTP Trigger in a real, runnable flow — captured live from the Studio editor, exactly as it looks on your canvas. This is the same workflow used for the example input & output below.

How it’s configured

The node’s settings as the builder shows them — every field laid out with real values. In the Studio these are edited on the node: click the chevron on the divider under its ports to open them.

Ports

This is a trigger — it starts runs and takes no input wire.

Ports are the node’s contract with its neighbours. In the editor a port label renders bold when wired and italic when optional; ◈ ports accept attachment carriers rather than data wires.

How data flows through it

As a trigger, HTTP Trigger starts runs — it takes no input wire. What it emits is the request wrapper: the event’s body becomes the payload, and the wrapper carries the event metadata around it (for an HTTP-style trigger that’s headers.*, request.method, request.path and query). Downstream nodes consume the content — the wrapper is unwrapped at each node boundary, and expression roots like {{ headers.x }} still resolve against the wrapper when you need the metadata. See Runs & run data for the envelope model.

Expressions in the config

String-typed properties accept {{ }} expressions evaluated against the incoming item at run time — e.g. {{ $json.customer.email }}. On this node that’s path, specPath, authUser, authPassword, authHeaderName, authHeaderValue, authToken, jwtSecret, jwtPublicKey, ipAllowlist. JSON- and code-typed fields never interpolate — they are passed through literally.

Build it with AI

Every node in this reference is reachable through Flowdrome’s AI Copilot and the MCP tools — say what you want, and the graph surgery happens server-side. Node types resolve fuzzily, so the catalog label (HTTP Trigger) works as well as the exact type id (input.http.webhook).

In the Copilot panel (or any connected AI):

create a workflow that starts with http trigger and logs the result

As a step in a create_chain_workflow call:

{"type":"HTTP Trigger","config":{}}

curl -s -X POST http://localhost:4800/mcp -H "content-type: application/json" -d '{ "jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": { "name": "add_node", "arguments": { "workflowId": "<id>", "type": "HTTP Trigger" } } }'

Example input & output

Captured from a real test run of the workflow above — this is what the Runs view shows after pressing Test workflow.

Input — what the node received

Output — what the node produced

Property reference

Every setting, with its type and default — the same fields shown configured above.

Using it

One endpoint (the default)

Leave Routes empty and the trigger is a classic webhook: one HTTP method + Path (POST /webhook/new), the parsed body arriving as $json, the request metadata riding the envelope (request.method, request.path, headers.*, query). Wire output into your flow.

Where it actually listens

Every path is served under a segment named after the workflow. A workflow called Dog Shop with a route GET /buy answers at:

https://your-host:8080/dog-shop/buy

The segment is the workflow’s name, lowercased, with runs of punctuation collapsed to a single dash. There is no per-trigger port — the host has one listener and every deployed workflow shares it, which is why the workflow name is what keeps them apart. Two workflows can both define /buy and neither shadows the other.

What the caller gets back

A deployed webhook is an async job. It answers the moment the run starts — it does not hold the connection open for the length of the run:

POST /dog-shop/webhook/new
→ 202 Accepted
  { "runId": "run_a1b2c3", "status": "running", "statusUrl": "/api/serve/runs/run_a1b2c3" }

Collect the outcome from that URL:

GET /api/serve/runs/run_a1b2c3
→ 200 { "runId": "run_a1b2c3", "workflowId": "orders", "status": "succeeded",
        "durationMs": 412, "output": { … } }

status is one of queued, running, paused, succeeded, failed, canceled; output appears once the run has one and error when it failed. The endpoint needs no session — the unguessable run id is the capability — and it answers 404 for an id it has never seen. It resolves from the live engine and then from the durable run record, so the answer survives the run being evicted from memory and survives a host restart. It deliberately carries the run’s outcome only, never the node-by-node execution trace.

Want the answer inline instead? Put an HTTP Response node in the workflow. That node declares a synchronous contract — it picks the status code, the content type and the body, and the caller gets that reply rather than the 202 envelope. The trade is the wait: on the synchronous path the host runs the workflow to a terminal state and then builds the reply from that node’s recorded output, so the caller holds the connection for the whole run.

Want the answer if it’s quick? Prefer: wait=N

Polling is the right default, but it is overkill for a workflow that finishes in 20 ms. Send Prefer: wait=N (seconds) and the request holds for up to that long:

POST /dog-shop/buy      Prefer: wait=5
→ 200 { "runId": "run_a1b2c3", "status": "succeeded", "durationMs": 412, "output": { … } }

If it does not finish in the budget you get the ordinary receipt, and the run carries on — it is never cancelled or restarted because you stopped waiting:

POST /dog-shop/import   Prefer: wait=5      (the run takes 30s)
→ 202 { "runId": "run_d4e5f6", "status": "running", "statusUrl": "/api/serve/runs/run_d4e5f6" }

The budget is capped at 60 seconds — the header arrives from the caller, and a request asking to be held for an hour is a request to occupy a connection for an hour. An absent, unparseable, zero or negative wait behaves exactly as if the header were not there.

A run that fails inside the budget comes back as 500 with the failure rather than a receipt:

POST /dog-shop/restock  Prefer: wait=5      (the run throws after 300ms)
→ 500 { "runId": "run_9f3c1a", "status": "failed", "error": "…" }

Prefer: wait applies to this async path only. A workflow that contains an HTTP Response node already runs synchronously — the caller holds the socket for the whole run, with no bound at all — so the wait code is never reached and the header does nothing there.

Answering with a 4xx

A 202 is an acceptance, not a result: it says the run started. A workflow that finished and failed still returned 202, so a caller must collect the run to know.

To answer with a real status code, put an HTTP Response node in the workflow — it picks the code, the content type and the body. That reply reaches the caller either way:

• Synchronously, as the response to the original request.
• On collection, as httpStatus on the status endpoint — so a caller that took the receipt still learns the workflow answered 401, 404, 409, whatever it chose.

GET /api/serve/runs/run_a1b2c3
→ 200 { "status": "succeeded", "httpStatus": 401, "output": { "error": "unauthorized" } }

httpStatus is absent when the workflow never executed an HTTP Response node — inventing a 200 there would claim an answer that was never given. Note that a rejected request is a succeeded run with a 401 answer, not a failed one; status and httpStatus mean different things.

What a synchronous workflow answers when it never reaches the node

Adding an HTTP Response node anywhere in the graph switches the whole trigger to the synchronous contract, and the graph may or may not reach it. Three outcomes:

The 500 matters because this path is synchronous: the caller already waited for the entire run, so a contentless 202 meant it waited, learned nothing, and still had to go and poll. The 202 on the success-without-replying case is the honest answer instead — a workflow that answers on one branch only has no response to give on the others.

Retries and Idempotency-Key

Because the caller gets an id rather than a finished result, retrying is natural — and a retry must not run the work twice. Send an Idempotency-Key header and a repeat returns the original run id without starting anything:

POST /dog-shop/webhook/new   Idempotency-Key: order-9931
→ 202 { "runId": "run_a1b2c3", … }

POST /dog-shop/webhook/new   Idempotency-Key: order-9931   ← same key, retried
→ 202 { "runId": "run_a1b2c3", … }                    ← same run. Nothing ran twice.

Keys are scoped to the deployed workflow, so two integrations that both send 1 never collide, and they last 24 hours. Concurrent retries with one key still produce exactly one run. The header is optional: send no key and every request starts its own run, as before.

A whole API from one trigger

Add rows to Routes and the trigger becomes a multi-endpoint front door — each route is its own output port:

Leave the Output port blank and it’s auto-named from the method + path (GET /users/{id} → get_users_id) — a route gets its own output handle the moment you add it; name it only when you want a specific one.

Routes are checked top to bottom — first match wins. Template parameters land on the payload as pathParams ({{ $json.pathParams.orderId }}), the request body’s own fields stay on $json, and the envelope (headers, query, request metadata) survives the hop so a downstream Check can still read headers.authorization.

Anything no route claims leaves on the fixed unmatched port — wire your 404 branch there. When a known path was hit with the wrong verb, $json.methodMismatch is true, so an If on the unmatched lane splits a real-API 405 from the plain 404. This is exactly the shape the mock API wizard generates.

Securing it

Authentication gates every endpoint of the trigger before any routing: Basic, Bearer, custom header, or JWT. A request that fails auth leaves on the optional unauthorized port with the failure detail — wire it to a 401 response so the workflow (not the ingress) decides the answer. Ingress guards (body cap, per-IP rate limit) apply per trigger.

Validating what arrives

This trigger does not check the body. It validates the method, the path and the content type, and then hands whatever arrived to the graph — there is no body-schema option here. A request missing a field you needed therefore fails wherever that field first matters, which is often after you have already called someone else’s API. Two ways to move the failure earlier:

• Body path on the HTTP Request node. It picks the value that becomes the outbound request body, and a path that is not present throws HTTP_REQUEST_BODY_MISSING — body path is missing: customer — before the request is built or sent. Cheap, and it guards exactly the value you were forwarding. Present-but-null counts as present: the check is whether the path exists.
• Validate JSON Schema after the trigger, when you need the whole shape — types, enums, required lists. With Route invalid on (the default) a bad body leaves on the invalid port with valid: false, the original input, and an errors array of path / code / message entries; wire that to a 400 response.

The triggers concept page has the worked curl example for both.

Publish an OpenAPI spec

Turn on Publish OpenAPI spec and the trigger serves a generated OpenAPI 3.0 document — built from its own routes — at the Spec path (default /openapi.json, GET). Callers (and Flowdrome’s own OpenAPI node) can discover every endpoint the trigger exposes without you hand-writing a spec. A real route always wins over the spec path, so it never shadows your API.

Tips

• Test without serving: the trigger tester (▶ on the node) pre-fills a wrapped request and gives you a route picker, an auth field that writes the right header for the trigger’s scheme (Basic / Bearer / JWT / custom), and a free-form headers box. All three write into the JSON below them, so anything they cannot express is still hand-editable — type an unknown path to exercise the unmatched lane, or a wrong credential to exercise unauthorized.
• Routed triggers register every verb for their path templates at the serve layer; the wrong verb still reaches the workflow so your 405 branch answers — like a real API, and unlike a hard ingress rejection.
• The Method/Path fields are ignored once Routes exist (the editor hides them) — routes are absolute path templates.
• Leave a route’s Output port blank to auto-name it from the method + path; set one only when you want a specific handle (keep it short — getOrder, not get order by id — v2).
• The retired Router node did this as a separate hop; existing workflows that still contain one keep running, but new graphs should put routes on the trigger.

Related nodes

The rest of the Input group — the same folder you’d scan in the editor’s library.

• Telegram Trigger Starts the workflow for every Telegram bot update — long-polls getUpdates (default) or serves a secret-token-v
• WhatsApp Trigger Starts the workflow when a WhatsApp message arrives (Meta Cloud API webhook)
• Slack Trigger Starts the workflow when a Slack event arrives (Events API)
• Discord Trigger Starts the workflow when a Discord message arrives — via the Gateway WebSocket (real-time messages) or an inte
• WebSocket Trigger Accepts a persistent WebSocket connection; each inbound message starts the workflow, and data sent to its feed
• Inject Injects static manual test payloads as workflow input.
• Manual Trigger Starts the workflow when run manually, passing your run/test data forward (empty item by default).
• Schedule Fires on a cron schedule or fixed interval, emitting a tick with the fire time.

This page is generated from the node registry by gen-node-docs.mjs on every site build — ports, properties, defaults and visibility rules cannot drift from the code. The screenshots and example data are captured from a live Flowdrome by npm run shots:nodes and npm run gen:examples. The hand-authored notes above are merged in.