Skip to content

# HTTP Request Action

The HTTP Request action allows the Activity to make an HTTP request to a remote URL. The response from the target server can be captured for further processing by expressions.

Variable substitution using the standard `${{expression}}` syntax is supported in all request text fields. This is particularly useful in the HTTP GET query parameters, allowing them to be dynamic. It is recommended that the variable value be URL-escaped, which is straightforward by simply wrapping the variable name in a `urlencode()` function call like this: `${{urlencode(varname)}}`.

The Ignore self-signed/invalid SSL certificate checkbox lets you tell Reactor to allow SSL connections when the SSL certificate of the server cannot be validated. Many local APIs use self-signed certificates, which will fail certification validation. Checking this box allows the connection to these endpoints, but introduces the possibility that another server may be substituted or a "man-in-the-middle" attack perpetrated against your request. Make sure you know and trust the endpoint if you check this box.

Like -k in `curl`

Checking this box is the same thing as using the `-k` option in a `curl` request. If you test your endpoint connection and it requires the use of `-k` or `--insecure` (or that's the default for your `curl` settings), then checking this box will be required for Reactor to connect to the server as well.

You may specify HTTP headers, one per line, to be sent with the request. Request headers are of the form `headername: headervalue` (e.g. `Accept: application/json`).

On POST queries, a data field is displayed allowing you to specify what data is to be sent. The action will automatically supply a `Content-Length` header for all POST requests, so you do not need to generate this yourself. Take care, however, that your headers include the correct Content-Type header for the type of data being sent.

The action can optionally capture and store the response data to a (expressionless) variable. If the server identified the response type as JSON data (i.e. the MIME type given in the server response headers is `application/json`), then the response will parsed as JSON and stored. Otherwise, the response is stored as plain text. By default, the response data is stored directly on the selected target variable (if any); null is stored if the request fails. If the Store response in advanced form checkbox is checked, the response data is stored in an object that includes status fields returned by the client library and server), whether the request is successful or not. The advanced response object is structured as follows:

        {
            ok: (boolean),
            data: (varies),
            status: (number),
            message: (string)
        }

The `ok` field (true or false) indicates if the request was successful. The `data` field contains the response body data. The `status` field contains the HTTP status code returned by the server, if it accepted the request and responded. If the server could be contacted (e.g. failed DNS lookup or didn't accept request/connection) the `status` will be 499. The `message` (string) is server- and implementation-specific; its contents are not defined or guaranteed, and should not be relied upon for other than troubleshooting.

Prefer `ok` to `status`

While 200 is the most common HTTP status code for a successful request, it is not the only code indicating success, and so it is recommended that `ok` be used in preference to checking `status` for success.

When the action is configured to capture the server response, it always waits until the request has completed and the response is stored. If you elect to ignore the response, the reaction will continue immediately after sending the request unless the Wait until request completes checkbox is checked.

Normally when an HTTP error occurs or the server is unreachable/unresponsive, an alert is issued (shown in the Status page). If you do not wish to see these alerts, you can check the Suppress alerts on HTTP errors checkbox. Errors will then only appear in the log file.

## Timeout

The default request timeout is 15 seconds. The timeout can be adjusted by setting the `http_request_action_timeout` configuration value (in the `engine` section of `reactor.yaml`) to the desired number of milliseconds (one second = 1000 milliseconds). This is an engine-wide setting; the timeout is the same for all HTTP Request actions made by Reactor and is not configurable on a per-request basis.

## Response Size Limit

Because a server can return a response of virtually any length, and the response is necessarily buffered in RAM and also possibly stored in state for other expressions to use, it is necessary to limit the number of bytes accepted from the remote host. Were this not true, it would be possible for the remote host to return a response of such a size that would cause your system to instantly crash (a condition that may be very hard to troubleshoot, as it may appear to happen randomly).

The default limit is 8192 bytes (8KB). Responses larger than the limit are truncated. This may cause errors in other expressions — the classic example is a large JSON response that becomes unparseable when truncated.

The limit can be increased by setting `http_request_action_maxresponse` (in the `engine` section of `reactor.yaml`) to the desired value (units are KB, 1KB=1024 bytes). Caution must be exercised, however, as the capacity of the system to store and handle large responses is not infinite. Values much larger than 2048 (2MB) bytes should be regarded with suspicion. Erratic operation of Reactor or system crashes may result if the limit is set too high. There is no hard rule, however, as the actual limit your system can tolerate will depend on the amount of available RAM.

Try to Use Optimal Queries!

Your first, best option is to try to use queries that give you the data you need with the smallest response size possible. When querying a weather service, for example, a query that is as specific as possible may yield a desirable compact response, as opposed to requesting a multi-day forecast but using only current conditions from the response.

## Errors

Errors in the request or at the server will be logged to the Reactor log file. If the action is configured to store the response data, the stored data will be null if an error occurs on the request (either directly on the variable or in the advanced format result object).

Check the Log!

If your query is not performing as expected, always check the log file before asking for help. Because of the wide range of possible services to which this facility can connect, you are expected to be the expert on your target and its possible responses. It is too difficult to remotely troubleshoot queries to an even more remote service, and study and interpret the documentation and details of every endpoint you might choose to contact, so the author will not provide support for specific connectivity or response issues arising from your use of this action.

Updated: 2025-May-21