Start by telling these four capabilities apart, before you use any of them

Add-on 22.0.1 bundles Node-RED 5.0.2. HTTP In opens a route that lives on your Node-RED backend, and HTTP Response is the only node that can finish that same request. HTTP Request runs the other way: your flow acting as a client, calling out to someone else's HTTPS service. The fourth capability is easy to overlook because it does not look like networking at all — the API node bundled with the HA WebSocket integration, which reaches Home Assistant directly and carries whatever privileges that integration's own connection already has. All four involve something you could reasonably call an API. Their trust source, their credentials, and what happens when they fail do not have that much in common.

The Add-on also declares host_network: true, which gives the container broader access to the local network than a typical add-on gets.

If you have not already, it is worth returning to the bounded testing habit from the debugging chapter before you go further: confirm your validation logic on pure, disconnected data first, and only bring the network into it once that logic is already proven.

flowchart LR
  A["A caller somewhere
on the network"] --> B["HTTP In receives the request;
HTTP Response answers it"]
  C1["A flow you built"] --> D["HTTP Request sends to
an external HTTPS service"]
  C2["A flow you built"] --> E["HA API node calls Home Assistant
with the integration's own privileges"]
  F["Webhook, WebSocket,
TCP, or UDP"] -.->|"its own rules,
not this chapter"| G["A different lifecycle entirely"]

HTTP In and HTTP Response are one exchange, not two separate nodes

HTTP In emits a message the instant it receives a request. For a GET, msg.payload is the query object. For POST, PUT, PATCH, and DELETE, the payload is the parsed request body — or the raw data, if you disabled parsing. Alongside the payload, the same message quietly carries two more fields: msg.req and msg.res. HTTP Response needs msg.res to answer over the original connection. Without it, the node only warns that no response object exists; it cannot invent one.

In the HTTP In editor you can pick GET, POST, PUT, DELETE, or PATCH. POST can turn on file uploads, and POST, PUT, PATCH, and DELETE can all skip body parsing entirely. Uploads land in memory, so the route needs its own limit on both size and file count — do not assume one exists by default. Node-RED's JSON and URL-encoded parsers use apiMaxLength, and when it is not set, the core default is 5mb. That is only a parser ceiling. It is not a sensible limit for your application's actual payload, and it covers neither a proxy's own limit nor a multipart upload.

The CSV, HTML, JSON, XML, and YAML parser nodes handle syntax only, the same way they were introduced back in the messages chapter. None of them can tell you whether a field was authorized, whether the resource cost is reasonable, or whether the content itself deserves to be trusted. For anything arriving from outside, the order is always the same: limit bytes and content type first, parse second, and validate the shape last.

Design the route on paper, in six steps, before you deploy anything

For a route that has real consequences, writing the contract down first is not paperwork for its own sake. It is how you notice a missing error branch, or a byte limit you never actually set, while fixing it still costs you nothing. The six steps below are the version of that habit this chapter asks for — and every one of them can be done with the route sitting disabled.

1. Step 1

   Write a contract for one route

   Specify one method, one relative path, the allowed content type, a maximum byte count, the required fields, the success status, the rejection status, and a timeout. Use only /PLACEHOLDER_HTTP_PATH for the path — never a real host or a real secret.

2. Step 2

   Map every terminal path

   Trace the normal, missing-field, wrong-type, unauthorized, internal-error, and timeout branches leaving HTTP In. Every one of the six has to reach HTTP Response. Never park a live msg.req or msg.res in a Delay node, in context, or on a path that waits on an external event with no bound.

3. Step 3

   Review the safe example offline

   This chapter's exercise is read-only: open the site's disabled example, 12-http-endpoint.json, and confirm it holds exactly four nodes, that HTTP In and HTTP Response both carry d:true, and that the path is entirely a placeholder. Do not import it, deploy it, enable it, or send it a test request. Reading the site's own isolated-import instructions is a separate step, and never counts as approval to deploy or connect anything.

4. Step 4

   Check the exposure and authentication layers

   Document Ingress and the direct host port as two separate things. If the route might be reached through a direct /endpoint/ path, plan on http_node.username/password or a controlled reverse proxy. Remember that this Basic Auth mechanism is not fine-grained authorization — it is next.

5. Step 5

   Review the outbound design

   Read the paired offline example, 13-outbound-http-request.json. Confirm its URL is PLACEHOLDER_HTTPS_URL, that HTTP Request carries d:true, that there are no authentication, TLS, or proxy references anywhere in it, and that Inject will not fire at startup.

6. Step 6

   Complete a failure-acceptance table

   For each case, record the expected status, the minimal body, the permitted headers, the external timeout, and the stop condition. Network and HA nodes stay disabled throughout, and every value stays a placeholder. Turning any of it on is a separate change, outside this chapter.

End-of-chapter offline acceptance

Ingress, the direct port, and /endpoint protect the route in three different ways

The Add-on wrapper fixes the Node-RED backend at 127.0.0.1:46836, sets userDir=/config/, nodesDir=/config/nodes, and flowFile=flows.json, and sets httpNodeRoot to /endpoint. So if you type /PLACEHOLDER_HTTP_PATH into HTTP In, the path the Add-on actually exposes is /endpoint/PLACEHOLDER_HTTP_PATH. Do not type /endpoint again inside the node's own path field — it is already there.

flowchart TD
  A["A request arrives at the Add-on"] --> B{"Which of the three
paths did it use?"}
  B -->|"Ingress"| C["Ingress NGINX accepts only
the Supervisor ingress source"]
  B -->|"Direct editor path, /"| D["Supervisor /auth protects it,
unless leave_front_door_open is on"]
  B -->|"Direct /endpoint/"| E["NGINX proxies straight to
the backend, skipping
Supervisor auth_request"]
  E --> F["Needs its own guard:
http_node username/password,
or a controlled proxy"]

When http_node.username/password includes a username, the wrapper hashes the password with its bundled bcryptjs library and passes the result to Node-RED as httpNodeAuth. That library is a wrapper dependency, not a node you drag into a flow.

Basic Auth answers only whether a caller holds the shared credentials. If different users are meant to reach different resources, the flow itself has to authorize them from a trusted identity source on top of that — and an error response must never leak which authorization check actually failed.

Every branch must respond, and must do so exactly once

Every Switch output, every bounded Catch branch, every validation-failure branch, and the normal branch all have to reach HTTP Response. Drop a branch, and the caller sits there until an upstream proxy or the client itself times out. Let two branches respond through the same msg.res, and you get a duplicate send. The safe shape is to build a fixed error envelope first, then set a controlled msg.statusCode and any header values at one single response convergence point.

flowchart TD
  S["HTTP In receives
the request"] --> V{"Validate method,
shape, and identity"}
  V -->|"normal"| R["HTTP Response,
one convergence point"]
  V -->|"missing field"| R
  V -->|"wrong type"| R
  V -->|"unauthorized"| R
  V -->|"internal error, from Catch"| R
  V -->|"timeout, from an external call"| R

This is what such a convergence point looks like as a shape guard, kept as a pure-data illustration:

Treat this as a shape guard only — it says nothing about identity, and it does not define a real route on its own. A status code fixed inside the HTTP Response node itself always wins. Otherwise the node reads msg.statusCode, falling back to 200 if that is not set either. For any non-Buffer object payload, it calls Express's res.jsonp(msg.payload), which means a JSONP callback name in the caller's query string can change the shape of the response envelope. If your contract requires invariant JSON, either reserve that callback query name for rejection, or serialize trusted JSON yourself and set a fixed JSON content type — both sidestep the JSONP behavior applied to plain objects.

Fix the destination in the node. Never let the message pick it.

HTTP Request 5.0.2 exposes editor fields for Method (GET, POST, PUT, DELETE, HEAD, or a value taken from msg.method), URL, GET payload handling, TLS configuration, authentication (Basic, Digest, or Bearer), keep-alive, HTTP proxy configuration, error output, the insecure HTTP parser, return type, and headers. If the node's URL field contains Mustache tags, the runtime renders them against the entire message — so a URL that looks fixed inside the node is not necessarily fixed at all. Any example here uses a complete, non-templated placeholder URL with no {{...}} in it; a real production destination needs its own, separate approval.

Beyond its own configured fields, the runtime also reads msg.headers, msg.cookies, and msg.followRedirects, as well as msg.method, msg.url, and msg.requestTimeout when those are left dynamic. When no TLS configuration is selected, it reads msg.rejectUnauthorized too. So immediately before this node, build a fresh, allowlisted message containing only the approved payload, the required headers, and fixed control values. Never pass an HTTP In, Dashboard, or MQTT message through unchanged, and do not treat deleting one or two known fields as equivalent to rebuilding it.

flowchart LR
  M["The message arriving
at this point in the flow"] --> N["Rebuild msg from scratch:
only approved payload,
headers, and control values"]
  N --> O["HTTP Request node,
fixed HTTPS URL and method"]
  O --> P["The one approved
external service"]
  M -.->|"never do this"| Q["Pass msg.url or msg.method
through unchanged"]
  Q -.->|"caller now picks
the destination"| X["Any host the network
can reach: SSRF"]

If httpRequestTimeout is not configured, the core runtime's HTTP Request timeout is 120000 ms, and a positive msg.requestTimeout can override it. The implementation also permits up to 21 redirects. These are Node-RED 5.0.2 behaviors, not a policy that suits every destination — that changes between builds, so set a narrower, justified timeout for each service you actually call, and bound both the retry count and the total deadline upstream of the node. Either disable redirects outright, or require an egress proxy to enforce a destination-host allowlist and a response-size limit. Never compensate for a timeout by adding unlimited retries.

The core runtime loads the entire response into memory before doing anything else with it. If parsed JSON is selected, it then runs JSON.parse before emitting the message. HTTP Request itself has neither a per-response byte limit nor a redirect-host allowlist, so checking msg.responseUrl, the content type, or the body size only after the node cannot undo an SSRF hit, a cross-host redirect, or memory exhaustion that already happened by that point. Still allowlist msg.statusCode, msg.headers, msg.responseUrl, msg.payload, msg.redirectList, and any msg.responseCookies on the successful output — understanding that this protects only how the data is used downstream, not the request that already happened. Do not pass headers or cookies unchanged into HTTP Response, and do not send the whole message to Debug.

Validate in layers, and answer every failure the same way

Selecting POST in HTTP In only performs the router's own method match. Complete validation needs at least a transport layer, a syntax layer, a shape layer, an authorization layer, and a business layer. A failure at any one of them must come back as a bounded, stable error — never a stack trace, a token, an internal host name, or the raw body echoed back.

CORS is not authentication. Node-RED can add CORS middleware to HTTP nodes through the global httpNodeCors setting and handle OPTIONS accordingly — the HTTP In dialog itself has no per-route CORS field. Permit only explicit origins, methods, and headers, and never combine a permissive wildcard with credentials. Remember, too, that the browser's same-origin policy does nothing at all to stop a non-browser client.

A reverse proxy in front of any of this has to limit request-body size, header bytes, connection count, and the upstream timeout, and it must trust only the forwarding headers it overwrites itself. Write down where TLS actually terminates, whether the proxy-to-backend hop stays protected, and how the client's real IP is obtained. The Add-on's own direct TLS covers only the direct listener — Ingress and any external proxy run their own, separate TLS sessions.

A bounded error model, spelled out

The HA API node is an advanced privileged entry point, not a general HTTP shortcut

In HA WebSocket 0.80.3, the registered node type is ha-api. It supports either WebSocket or HTTP; the HTTP methods are GET, POST, PUT, and DELETE, and the path has its leading /api/ stripped before being handed to your existing HA server configuration. WebSocket calls must include a type. Data can be plain JSON or JSONata, and both the output location and its type are customizable. Those dynamic capabilities let one node reach a great many HA APIs from a single place — they do not mean every call it can make is read-only.

If a Current State, Get Entities, or Action node already covers what you need, prefer that narrower node instead — the boundaries around an Action node's own target and data were covered in the earlier Action node chapter. Reach for the API node only when the case is genuinely advanced, no dedicated node exists for it, and the HA API contract is already fully established. This chapter provides no executable flow, method, path, or data for it, and does not instruct you to enable anything here.

ha-webhook is an HA event entry point, not an alias for Node-RED's HTTP In — the two do not share a lifecycle. A webhook URL or ID is itself a sensitive value and should never appear in a screenshot, a flow export, or a general log. You still need to constrain the external sources allowed to call it, guard against replay, cap the payload size, and bound whatever side effects follow. Other WebSocket, TCP, and UDP nodes each carry their own configuration and framing rules, and the paired HTTP In/HTTP Response model this chapter covers does not transfer over to them.

Fuller operational boundaries around credentials, proxies, TLS, host networking, and least privilege belong to the backup and security chapter later in this part of the guide. When timeout, memory, or connection problems come up, the performance and troubleshooting chapter after it is where to collect bounded diagnostic data — rather than reaching for full Debug output first.

The failures that actually happen

The ones that come up again and again

Where to go from here