Middleware Nodes

Middleware nodes let a funnel call an external system during routing, wait for the response, then decide what happens next.

They are similar to webhook nodes in that FunnelFlux sends visitor/funnel data to an external URL. The key difference is timing.

Webhook nodes send data out and let the funnel continue. Middleware nodes wait for the external response and use it to route the visitor.

Use middleware nodes when another system needs to make a live decision before FunnelFlux can continue.

What middleware nodes are useful for

Middleware nodes are useful when you want to:

• approve, reject, or segment a visitor before sending them further
• ask your own backend where a visitor should go
• route based on CRM, lead scoring, inventory, compliance, or fraud checks
• send form/action data to an external system and wait for the result
• choose a funnel path from an external realtime decision
• build advanced host-and-post, survey, qualification, or lead-routing flows

For example, a visitor could submit a form on a lander, then click through to a middleware node. FunnelFlux sends the form data and tracking context to your endpoint. Your endpoint returns a response such as "qualified", "reject", or "needs_review", and FunnelFlux routes based on that response.

Middleware nodes vs webhook nodes

Use webhook nodes when you want to notify another system.

Use middleware nodes when that other system must answer before routing continues.

In practical terms:

• webhook nodes are asynchronous pass-through nodes
• middleware nodes are synchronous decision nodes
• webhook delivery success/failure does not decide the visitor path
• middleware responses can decide the visitor path
• webhook nodes are safer for simple automation
• middleware nodes are more powerful, but your external endpoint becomes part of the live redirect path

This matters because middleware nodes add realtime dependency. If your endpoint is slow, broken, or returns something unexpected, FunnelFlux needs to use the default route.

Middleware configs vs middleware nodes

Middleware configs are reusable destination and route settings.

They define:

• the external URL to call
• request method
• timeout / response budget
• headers/authentication
• HMAC signing
• route rules based on the response
• the default fallback route

Middleware nodes are where those configs are used inside a funnel.

This means you can create one middleware config, then use it in one or more funnels.

Destination settings

The Destination tab controls where FunnelFlux sends the middleware request.

You can configure:

• destination type
• method: GET or POST
• timeout
• URL
• custom headers
• basic auth
• HMAC secret

POST requests send a JSON payload. GET requests sign the URL and do not send a JSON body.

Middleware endpoints must use an absolute HTTP or HTTPS URL. In production, use HTTPS. Local/private URLs are not suitable for live middleware destinations, so if you are testing locally, use a public tunnel or a hosted endpoint.

Secret fields may be blank when editing an existing config. This does not necessarily mean the secret is missing. Entering a new value replaces the saved one.

What data gets sent

Middleware requests include the current funnel and visitor context where available.

This can include:

• request ID and timestamp
• visitor/session identifiers
• current funnel and node information
• traffic source information
• tracking fields captured from the entrance URL
• current url_buffer values
• visitor tags
• action/form data submitted earlier in the funnel

This article is focused on usage, not the full technical schema.

For schema details, see the FunnelFlux API documentation:

Middleware API documentation

Routes and response matching

Middleware configs have routes.

Each route has a route key. This is the route identifier you use when connecting the middleware node to the next node in your funnel.

The default fallback route uses the key default. Non-default route keys should be simple lowercase values using letters, numbers, and underscores, such as qualified, reject, or needs_review.

Non-default routes have priorities from 1 to 255 and are evaluated in ascending order. The first matching route is used. If no non-default route matches, FunnelFlux uses the default route.

Routes can evaluate:

• response status code
• response body text
• JSON response keys, using body_json.<path> dot paths such as body_json.decision or body_json.items.0.score

For example, your endpoint might return JSON like:

{
  "decision": "qualified",
  "score": 87
}

You could then create a route that checks whether body_json.decision is qualified, and connect that route to your next page or offer path.

Always configure the default route as a safe fallback. This is what FunnelFlux uses when no route matches, the request times out, the endpoint fails, or the config cannot be used.

Adding a middleware node to a funnel

In the funnel builder, add a Middleware Node from the Add Nodes panel or canvas add-node menu.

Then open the node settings and choose the middleware config it should use.

Only active middleware configs are available in the picker.

After choosing a config, connect the middleware node's outgoing routes.

When you drag a connection from a middleware node, FunnelFlux asks which route key that connection should use. Each route should connect to the next funnel node you want that route to follow.

You may see override controls in the node settings for headers, basic auth, or HMAC. These are not currently editable from the node. Configure those settings on the middleware config itself.

Changing configs and routes

Be careful when changing a middleware config after it is used in active funnels.

If you change the selected config on a middleware node, existing outgoing route connections may be removed because the route set has changed.

If you edit route definitions inside a middleware config, active funnels using that config may need their connections checked again.

After changing routes, open any funnel that uses the config and confirm:

• every route that should be usable has a connection
• the default route goes somewhere safe
• your test traffic follows the expected route

Testing middleware nodes

There is no dedicated "send test request" button in the current UI.

The practical test flow is:

1. Create or update your middleware config
2. Add the middleware node to a funnel
3. Connect the middleware routes
4. Save the funnel
5. Send test traffic through a real funnel/tracking link
6. Check Reporting > Logs > Middleware Logs

Your external endpoint must be reachable when you test. If you are testing with Zapier, Make, n8n, Pipedream, or a custom webhook tool, make sure the listener is active before sending test traffic.

For local development, use a public tunnel or hosted endpoint. FunnelFlux blocks private, loopback, link-local, and reserved IP destinations for live routing safety.

Timeouts and fallback behavior

Middleware nodes wait for a response, but they should not wait forever.

Set a timeout that is realistic for live redirect traffic. Shorter is usually better. If the external endpoint does not respond in time, FunnelFlux falls back to the default route.

Timeouts can be configured from 1 ms to 30 seconds. Runtime defaults to 5 seconds if no timeout is set.

In API payloads this response budget is exposed as execute_timeout_ms. Your endpoint should respond comfortably inside that budget, not exactly at the limit. Leave a safety buffer for network latency and temporary slowdowns.

Fallback can happen when:

• the endpoint times out
• the endpoint cannot be reached
• the config is disabled or inactive
• billing access is unavailable for the request
• the destination is invalid
• no non-default route matches
• the response is not in the format your route rules expected
• the default route is not wired from the funnel node

This is why the default route matters. Do not send the default route somewhere random. Send it to the safest general path for that funnel.

Middleware logs

Middleware logs show what happened for each middleware request.

Use them to confirm:

• whether the request matched a route
• which route key was matched
• the HTTP status code returned by your endpoint
• request latency
• request and hit identifiers for debugging

In API responses, matchedRouteID is the route key that matched, such as qualified or default.

Simple use cases

Use middleware nodes for live decisioning.

Examples:

• submit lead form data to your own API, then route accepted leads to one path and rejected leads to another
• ask a CRM whether a visitor already exists, then avoid duplicate submission paths
• score a survey response externally, then route high-score and low-score users differently
• check product or appointment availability before sending the visitor to a booking path
• apply a compliance or fraud screen before sending traffic to a sensitive offer
• build a host-and-post style flow where your own system decides which funnel path should receive the visitor next

If you only need to send data somewhere and do not need the response for routing, use a webhook node instead.

Common mistakes

Do not use a middleware node for simple notifications. Use a webhook node for that.

Do not make your external endpoint slow. Middleware runs inside the live routing path, so endpoint speed directly affects the visitor.

Do not forget the default route. It is the safety path when the request fails or does not match.

Do not forget to wire the default route from the middleware node. This is the fallback route.

Do not rely on local/private URLs for production middleware. Use a public HTTPS endpoint.

Do not change route keys or response rules in active configs without checking the funnels that use them.

Do not build your endpoint around internal field names. The public payload field for buffered URL values is url_buffer.

Do not pass sensitive data through tracking URLs unless you are comfortable with that data being part of your tracking flow and middleware request.

Technical reference

This article focuses on how to use middleware nodes conceptually.

For the exact request/response schema, API endpoints, and field-level details, use the FunnelFlux API documentation:

Middleware API documentation

Updated on: 16/06/2026