> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.funnelflux.pro/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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.

![Middleware Nodes asset list](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/middleware-asset-list_1ahj9az.png)

## 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.

![Middleware destination settings](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/destination-settings_16j9n97.png)

## 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](https://api-docs.funnelflux.pro/middleware)

## 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:
```json
{
  "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.

![Middleware route settings](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/middleware-routes_1fjj0un.png)

## 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.

![Middleware node settings](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/node-settings_13ob58i.png)

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 can override headers, basic auth, and HMAC on the node itself. These node overrides do not change the destination URL, method, or destination type. To call a different endpoint, duplicate the middleware config.

## 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.

![Middleware logs](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/middleware-logs_1f1tq3q.png)

## 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 default to 5 seconds. Middleware basic caps at 10 seconds. Middleware Pro allows 30 seconds for a live wait, or up to 60 seconds when a loading page is enabled so the visitor sees an interstitial while the request runs.

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](https://api-docs.funnelflux.pro/middleware)