MuleSoft HTTP Listener and Request
The HTTP Listener and HTTP Request components are the two most used components in MuleSoft. The HTTP Listener receives incoming traffic into your application. The HTTP Request sends outgoing calls to external services. Together they form the foundation of almost every integration you will build.
HTTP Listener: Receiving Incoming Requests
Think of the HTTP Listener as the front door of your application. When a client — a browser, a mobile app, or another service — sends an HTTP request to your Mule application, the HTTP Listener opens the door and starts the flow.
HTTP Listener Configuration Properties
Connector Config (shared across all listeners): Host: 0.0.0.0 (listen on all network interfaces) Port: 8081 (default Mule port) Protocol: HTTP or HTTPS Per-Listener Properties: Path: /orders (the URL path) Method: GET, POST, PUT, DELETE, PATCH, or ANY Response: status code and body settings
Listener Path Patterns
/orders → matches exactly /orders
/orders/{id} → matches /orders/123, /orders/ORD-001
/orders/{id}/items → matches /orders/123/items
/files/* → matches /files/report.csv, /files/data/export.xlsx
/* → matches anything (catch-all)
HTTP Listener Response Configuration
Every HTTP Listener has a response section. Configure the status code, headers, and body that the listener returns to the caller after the flow finishes.
HTTP Listener Response:
Status Code: #[vars.httpStatus default 200]
Headers:
Content-Type: application/json
X-Request-Id: #[vars.correlationId]
Body: #[payload]
Reading All Parts of an Incoming Request
Incoming Request Anatomy Diagram
GET /products?category=books&page=2 HTTP/1.1
Host: localhost:8081
Authorization: Bearer eyJhbGc...
Content-Type: application/json
X-Correlation-Id: REQ-9991
{ "filter": "published" }
In MuleSoft:
attributes.method = "GET"
attributes.requestPath = "/products"
attributes.queryParams.category = "books"
attributes.queryParams.page = "2"
attributes.headers.'Authorization' = "Bearer eyJhbGc..."
attributes.headers.'X-Correlation-Id' = "REQ-9991"
payload = { "filter": "published" }
HTTP Request: Calling External Services
The HTTP Request component sends a request from your Mule application to an external HTTP endpoint. When your flow needs to call a REST API, fetch data from a third-party service, or invoke another Mule API, HTTP Request does the job.
HTTP Request Configuration
Connector Config (reusable):
Host: api.weather.com
Port: 443
Protocol: HTTPS
Base Path: /v1
Per-Request Properties:
Method: GET
Path: /forecast
Query Params:
city: #[vars.cityName]
days: 7
Headers:
X-API-Key: #[p('weather.apiKey')]
Full HTTP Request and Response Flow
Call an External API and Return Its Data
Client
| GET /weather?city=London
v
[HTTP Listener: /weather]
| reads: attributes.queryParams.city = "London"
v
[Set Variable: cityName = "London"]
v
[HTTP Request: GET api.weather.com/v1/forecast?city=#[vars.cityName]&days=7]
| External API returns:
| { "city": "London", "temp": 12, "condition": "Cloudy" }
| This becomes the new payload
v
[Transform Message: format the response]
%dw 2.0
output application/json
---
{
"location": payload.city,
"temperature": payload.temp ++ "°C",
"weather": payload.condition
}
v
[HTTP Listener Response: 200, { "location": "London", "temperature": "12°C", ... }]
v
Client receives the formatted weather data
Setting Request Headers
Many external APIs require authentication headers or custom headers. Set them in the HTTP Request configuration or dynamically using DataWeave.
HTTP Request Headers (static): Authorization: Bearer abc123xyz Accept: application/json HTTP Request Headers (dynamic, from variables): Authorization: Bearer #[vars.accessToken] X-Tenant-Id: #[vars.tenantId] X-Request-Id: #[uuid()]
Sending a POST Request Body
Flow: createExternalOrder
[HTTP Listener: POST /orders]
| payload = { "product": "Pen", "qty": 10 }
v
[Transform Message: adapt to external API format]
%dw 2.0
output application/json
---
{
"item": payload.product,
"quantity": payload.qty,
"source": "estudy247"
}
v
[HTTP Request: POST /api/orders at supplier.com]
| sends: { "item": "Pen", "quantity": 10, "source": "estudy247" }
| receives: { "orderId": "SUP-4421", "status": "accepted" }
v
[Set Variable: supplierOrderId = payload.orderId]
v
[Database: save supplierOrderId to local orders table]
Handling HTTP Request Errors
When the external server returns an HTTP 4xx or 5xx response, MuleSoft raises an error by default. Catch these errors in the error handler.
Error Handler for HTTP Request Errors:
On Error Propagate: HTTP:NOT_FOUND
[Set Payload: {"error": "External resource not found"}]
[Set Variable: httpStatus = 404]
On Error Propagate: HTTP:UNAUTHORIZED
[Set Payload: {"error": "Authentication failed with external service"}]
[Set Variable: httpStatus = 502]
On Error Propagate: HTTP:TIMEOUT
[Logger: "External API timed out"]
[Set Payload: {"error": "External service unavailable, try again later"}]
[Set Variable: httpStatus = 503]
On Error Propagate: ANY
[Logger: "Unexpected error: #[error.description]"]
[Set Variable: httpStatus = 500]
HTTP Request Timeout Configuration
Always set a timeout on HTTP requests to external services. Without a timeout, a slow or unresponsive external API blocks your thread indefinitely.
HTTP Request Connector Config: Response Timeout: 10000 ms (10 seconds) Connection Idle Timeout: 30000 ms (30 seconds) Reconnection Strategy: Reconnect: true Frequency: 2000 ms Blocking: false
Following Redirects
Some external APIs redirect requests (HTTP 301 or 302). Configure the HTTP Request connector to follow redirects automatically by enabling Follow Redirects in the connector settings. Set a max redirect count (typically 5) to prevent redirect loops.
HTTPS and TLS Configuration
For HTTPS requests to external APIs, set the protocol to HTTPS in the connector config. If the external API uses a self-signed certificate, add the certificate to a TLS trust store and reference it in the connector configuration. For standard certificates from public CAs, no additional TLS configuration is required — MuleSoft trusts standard certificates by default.
Performance Tip: Connection Pooling
When your flow calls the same external API frequently, use the same connector configuration across all HTTP Request components in the project. MuleSoft reuses connections from the pool instead of opening new ones for each request. Set Max Connections in the connector config to match your expected concurrency. A good starting value for most APIs is 10 maximum connections.