---
id: web--http-listener
title: "Http listener"
summary: "Embedded web server: listens on a port and path, emits every incoming request as a `WebHttpRequest` and sends the response it receives back on its `Input` pin (or from an **Http response** component). Use it to expose a flow as an HTTP endpoint."
audience: user
keywords: "start, output, input, authentificate, listenurl, maxparallelrequests, maxrequestbodysize, timeout, keepalivetimeout, maxrequestheadercount, keeprawbody, usessl, sslprotocol, servercertificate"
---
# Http listener

Embedded web server: listens on a port and path, emits every incoming request as a `WebHttpRequest` and sends the response it receives back on its `Input` pin (or from an **Http response** component). Use it to expose a flow as an HTTP endpoint.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Start | start | | Starts the server. Called by the system at flow start when unconnected. |
| Output | output | `Viaducta.Plugins.Http.Types.WebHttpRequest` | Called for every request (after authentication). Connect Rest handler, SOAP handler or your own logic. |
| Input | input | `Viaducta.Plugins.Http.Types.WebHttpResponse`, `Viaducta.Plugins.TextPlugin.Types.TextRecord` | Response to send to the caller of the current request. |
| Authentificate | continue | `Viaducta.Plugins.Http.Types.WebHttpRequest` | Called first for every request. An error here rejects the request. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `ListenUrl` | listener URL | | Required. Format `http://<host>:<port>/<path>`, see below. |
| `MaxParallelRequests` | integer (1-4096) | `1024` | Max requests processed in parallel. Further requests wait for a free slot until the caller gives up; open (keep-alive) connections are not limited. |
| `MaxRequestBodySize` | integer | `0` | Max body size in bytes, `0` = unlimited (2 GB). |
| `Timeout` | integer | `60000` | Ignored, see Notes. |
| `KeepAliveTimeout` | integer | `130` | Keep-alive timeout in seconds. |
| `MaxRequestHeaderCount` | integer | `100` | Max number of request headers. |
| `KeepRawBody` | boolean | `false` | `true`: also put the exact request bytes in `ByteBody` for text and form requests (`Body`/`Form` are still filled, `IsByteBody` stays `false`). Turn on when a signature over the body is checked, for example by the **Webhook receiver**. |
| `UseSsl` | boolean | `false` | `true`: HTTPS. |
| `SslProtocol` | dropdown: `0` None, `12` Ssl2, `48` Ssl3, `192` Tls, `240` Default, `768` Tls11, `3072` Tls12, `12288` Tls13 | `0` | Allowed protocol(s) when `UseSsl`. `0` = OS default. |
| `ServerCertificate` | certificate | | Name of a certificate object in the repository, used when `UseSsl`. |

### ListenUrl format

The editor writes `http://localhost:<port>/<path>` for a private listener (local machine only) or `http://0.0.0.0:<port>/<path>` for a public one (all interfaces), e.g. `http://0.0.0.0:9000/api`. `*` or `+` as host also means all interfaces; any other host must be an IP address. Only one URL is supported. A public listener is also reachable through the designer server at `<server>/env/<tenantId>-<environment>/<port>/<path>` (shown in the editor as the absolute URL).

## Behaviour

- Several listeners (and web socket listeners) in a flow can share a port if they use different paths under the same first segment (`/api/orders` and `/api/users`, not `/api` and `/api2`) and identical SSL, certificate and visibility settings; otherwise the flow fails to start.
- For each request: method, full URL, headers, query string, cookies and remote IP are copied into a `WebHttpRequest`. Form posts fill `Form`, text content types fill `Body`, anything else fills `ByteBody` (`IsByteBody` = `true`). A missing content type is treated as `text/json`. Request headers `ViaSessionId` and `ViaCorrelationId` are copied into the flow metadata session and correlation id.
- `Authentificate` is called first. Any error returns a JSON error (`message`, `code`, `type`, `flowName`, `componentName`, `traceId`); the status is `401` for errors raised by **Http authentification**, otherwise `500`.
- Then `Output` is called. No `Output` connection: empty `404`. If the flow finishes without sending a response: `500` "The response ... was never sent". Errors in the flow: JSON error, `500` (or the error's code if it requests that).
- The response: `StatusCode` (`0` = `200`), headers, cookies, `ContentType`, `Body` or `ByteBody`, `ContentFileName` (adds `Content-disposition: attachment`). A `TextRecord` becomes a `200` with `Value` as body. Only the first response per request is sent.
- The plugin keeps the flow running.

## Notes

- `Timeout` is not used: a request waits until the flow finishes.
- With only one listener on a port, it receives every path on that port, not only its own.
- With `UseSsl` and no `ServerCertificate`, the default development certificate is used and `SslProtocol` is not applied.
- Without an `Authentificate` connection all requests are served (warning shown in the designer).

## Example

```json
{ "ListenUrl": "http://0.0.0.0:9000/api", "MaxParallelRequests": 1024 }
```

**Http listener** → Rest handler → ... → Http response