Skip to main content

HTTP Receiver Data Source

The HTTP Receiver data source allows Mango to listen for incoming HTTP requests and accept data pushed from external systems. Unlike the HTTP Retriever (which polls remote endpoints), the HTTP Receiver acts as a webhook-style listener that waits for external systems to send data to Mango. This makes it ideal for event-driven integrations where the remote system controls when data is transmitted.

Mango provides both a standard HTTP Receiver (which accepts form-encoded or URL-parameter data) and an HTTP JSON Receiver variant (which accepts JSON-formatted request bodies). Both operate on Mango's built-in web server, so no additional server infrastructure is required.

Overview​

PropertyValue
ModulemangoAutomation-HttpReceiver
ProtocolHTTP/HTTPS
DirectionListening
Typical UseReceiving data via HTTP POST/PUT webhooks

Prerequisites​

  • An external system capable of sending HTTP POST or GET requests to Mango's URL.
  • The Mango server must be network-accessible from the external system (the sender must be able to reach Mango's HTTP port).
  • Knowledge of the data format the external system sends, including parameter names, value formats, and any timestamps.
  • If the external system sends JSON, use the HTTP JSON Receiver variant.
  • Firewall rules must allow inbound connections on Mango's HTTP/HTTPS port from the sending system.

Configuration​

Data Source Settings​

SettingDescription
NameA descriptive name for the data source.
Listener URL pathThe URL path on which Mango listens for incoming requests. External systems send data to http://<mango-host>:<port>/<path>.
Allowed IP addresses(Optional) A whitelist of IP addresses permitted to send data. Requests from other addresses are rejected. If left empty, all addresses are accepted.

The HTTP Receiver does not have an update period because it is event-driven: data points are updated whenever a matching HTTP request arrives, rather than on a polling schedule.

Data Point Configuration​

Each data point is mapped to a specific parameter or field in the incoming HTTP request.

SettingDescription
Data typeThe Mango data type (Binary, Numeric, Alphanumeric, Multistate). Incoming values are automatically converted.
Parameter nameThe HTTP request parameter name (for form-encoded or URL-parameter requests) or JSON field name (for JSON requests) that contains this point's value.
Time override parameter(Optional) The name of a parameter or field containing a timestamp for this value. If not specified, the request arrival time is used.
Time formatThe date/time format pattern used to parse the time override value (Java SimpleDateFormat).

HTTP JSON Receiver​

The HTTP JSON Receiver variant accepts JSON request bodies instead of URL-encoded parameters. The configuration is similar, but parameter names correspond to keys in the JSON object. For nested JSON structures, use dot notation or the appropriate path syntax to reference nested fields.

Example incoming JSON:

{
  "sensorId": "temp-01",
  "value": 72.5,
  "timestamp": "2026-02-16T14:30:00Z"
}

For this payload, configure a data point with parameter name value and time override parameter timestamp.

Common Patterns​

Receiving Webhook Notifications​

Many cloud services and IoT platforms support webhook callbacks. Configure the HTTP Receiver's listener URL path and provide the full Mango URL to the external service as the webhook destination. When the external service triggers an event, it sends an HTTP POST to Mango, and the receiver updates the corresponding data points.

Example workflow:

  1. Create an HTTP Receiver data source with listener path /api/webhook/alerts.
  2. Configure data points for each field in the webhook payload.
  3. Register https://mango.yourcompany.com/api/webhook/alerts as the webhook URL in the external service.
  4. When the external service sends a POST, Mango receives and stores the data.

Accepting Data from Edge Devices​

Lightweight edge devices (microcontrollers, Raspberry Pi nodes, custom gateways) that cannot run a full Mango instance can push readings directly to the HTTP Receiver using simple HTTP POST requests. This avoids the complexity of configuring a protocol-based data source and works well for custom or prototype hardware.

Example using curl from an edge device:

curl -X POST "http://mango-server:8080/api/receiver/sensors" \
  -d "temperature=72.5&humidity=45.2&timestamp=2026-02-16T14:30:00"

Bridging Systems with Custom Scripts​

Use scheduled scripts or cron jobs on external servers to extract data from legacy systems and push it to Mango via HTTP POST. This approach works for systems that cannot be directly polled by Mango but can run scripts that query local databases or APIs and forward the results.

Securing the Receiver​

For production deployments:

  • Use HTTPS to encrypt data in transit. Configure Mango's built-in SSL/TLS settings.
  • Configure allowed IP addresses to restrict which systems can send data.
  • Place Mango behind a reverse proxy (e.g., Nginx, Apache) for additional access control and rate limiting.
  • Use Mango's authentication mechanisms to require valid credentials in incoming requests.

Troubleshooting​

No Data Received​

  1. URL path mismatch -- verify the external system is sending requests to the exact listener URL path configured in the data source, including any leading slashes.
  2. Firewall blocking -- ensure inbound HTTP/HTTPS traffic is allowed from the external system to the Mango server.
  3. IP whitelist -- if allowed IP addresses are configured, verify the sender's IP is included. Check for NAT or proxy addresses that may differ from the expected IP.
  4. Wrong HTTP method -- verify the external system is using the expected HTTP method (POST or GET).
  5. Data source not enabled -- ensure both the data source and its data points are enabled.

Wrong Values or Missing Points​

  1. Parameter name mismatch -- the data point's parameter name must exactly match the parameter or JSON key sent by the external system (case-sensitive).
  2. Data type conversion failure -- if the incoming value cannot be converted to the configured Mango data type (e.g., a string value sent to a Numeric point), the point will not update.
  3. JSON structure -- for the HTTP JSON Receiver, ensure the JSON payload structure matches what the data points expect. Nested objects may require a path-based parameter name.

Timestamp Issues​

  1. Time format mismatch -- if a time override parameter is configured, the time format pattern must exactly match the incoming timestamp format. Test with simple formats first (e.g., ISO 8601).
  2. Time zone -- timestamps without explicit time zone information are interpreted in the Mango server's local time zone. Ensure the sender and receiver agree on time zone conventions.
  3. Missing timestamp -- if the time override parameter is configured but the incoming request does not include it, the data point may not update or may use an incorrect time.

Performance Concerns​

  1. High request volume -- if the external system sends many requests per second, Mango's web server may become a bottleneck. Monitor Mango's CPU and memory usage, and consider batching multiple values per request.
  2. Large payloads -- very large JSON or form payloads may cause parsing delays. Keep payloads focused on the data that Mango needs.
  3. Concurrent senders -- multiple external systems sending to the same receiver simultaneously is supported, but very high concurrency may require tuning Mango's web server thread pool settings.