HTTP Request

The http_request component lets you make HTTP/HTTPS requests. To do so, you need to add it to your device’s configuration:

# Example configuration entry
http_request:

Configuration variables:

  • id (Optional, ID): Manually specify the ID used for code generation.

  • follow_redirects (Optional, boolean): Enable following HTTP redirects. Defaults to true.

  • redirect_limit (Optional, integer): Maximum amount of redirects to follow when enabled. Defaults to 3.

  • timeout (Optional, Time): Timeout for request. Defaults to 4.5s.

  • useragent (Optional, string): User-Agent header for requests. Defaults to ESPHome/<version> (https://esphome.io) where <version> is the version of ESPHome the device is running. For example: ESPHome/2024.6.0 (https://esphome.io)

  • verify_ssl (Optional, boolean): When set to true (default), SSL/TLS certificates will be validated upon connection; if invalid, the connection will be aborted. To accomplish this, ESP-IDF’s default ESP x509 certificate bundle is included in the build. This certificate bundle includes the complete list of root certificates from Mozilla’s NSS root certificate store. May only be set to true when using the ESP-IDF framework; must be explicitly set to false when using the Arduino framework.

  • watchdog_timeout (Optional, Time): Change the watchdog timeout during connection/data transfer. May be useful on slow connections or connections with high latency. Do not change this value unless you are experiencing device reboots due to watchdog timeouts; doing so may prevent the device from rebooting due to a legitimate problem. Only available on ESP32 and RP2040.

For the ESP32 when using ESP-IDF:

  • buffer_size_rx (Optional, integer): Change HTTP receive buffer size. Defaults to 512.

  • buffer_size_tx (Optional, integer): Change HTTP transmit buffer size. Defaults to 512.

For the ESP8266:

  • esp8266_disable_ssl_support (Optional, boolean): Determines whether to include HTTPS/SSL support in the firmware binary. Excluding the SSL libraries from your build will result in a smaller binary, which may be necessary for memory-constrained devices (512 kB or 1 MB). If you see Error: ESP does not have enough space to store OTA file in your device’s logs, you may need to enable this option. Defaults to false. By setting this option to true:

    • HTTPS connections will not be possible

    • verify_ssl: false is implied

Warning

Setting verify_ssl to false reduces security when using HTTPS connections!

Without the root certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the HTTPS connection up to person-in-the-middle attacks.

To maximize security, do not set verify_ssl to false unless:

  • a custom CA/self-signed certificate is used,

  • the Arduino framework is used, or

  • the device does not have sufficient memory to store the certificate bundle

We strongly recommend using hardware which properly supports TLS/SSL.

HTTP Request Actions

The http_request component supports a number of actions that can be used to send requests.

http_request.get Action

This action sends a GET request.

on_...:
  - http_request.get:
      url: https://esphome.io
      headers:
        Content-Type: application/json
      on_response:
        then:
          - logger.log:
              format: 'Response status: %d, Duration: %u ms'
              args:
                - response->status_code
                - response->duration_ms
  # Short form
  - http_request.get: https://esphome.io

Configuration variables:

  • url (Required, string, templatable): URL to which to send the request.

  • headers (Optional, mapping): Map of HTTP headers. Values are templatable.

  • capture_response (Optional, boolean): when set to true, the response data will be captured and placed into the body variable as a std::string for use in lambdas. Defaults to false.

  • max_response_buffer_size (Optional, integer): The maximum buffer size to be used to store the response. Defaults to 1 kB.

  • on_response (Optional, Automation): An automation to perform after the request is received.

http_request.post Action

This action sends a POST request.

on_...:
  - http_request.post:
      url: https://esphome.io
      headers:
        Content-Type: application/json
      json:
        key: value
  # Short form
  - http_request.post: https://esphome.io

Configuration variables:

http_request.send Action

This action sends a request.

on_...:
  - http_request.send:
      method: PUT
      url: https://esphome.io
      headers:
        Content-Type: application/json
      body: "Some data"

Configuration variables:

on_response Trigger

This automation will be triggered when the HTTP request is complete. The following variables are available for use in lambdas:

  • response as a pointer to HttpContainer object which contains content_length, status_code and duration_ms.

  • body as std::string which contains the response body when capture_response (see http_request.get Action) is set to true.

on_...
  then:
    - http_request.get:
        url: https://esphome.io
        on_response:
          then:
            - logger.log:
                format: "Response status: %d, Duration: %u ms"
                args:
                  - response->status_code
                  - response->duration_ms
            - lambda: |-
                ESP_LOGD(TAG, "Response status: %d, Duration: %u ms", response->status_code, response->duration_ms);

Examples

Templatable values

on_...:
  - http_request.post:
      url: !lambda |-
        return ((std::string) "https://esphome.io?state=" + id(my_sensor).state).c_str();
      headers:
        X-Custom-Header: !lambda |-
          return ((std::string) "Value-" + id(my_sensor).state).c_str();
      body: !lambda |-
        return id(my_sensor).state;

POST Body in JSON format (syntax 1)

Note: all values of the map must be strings. It is not possible to send JSON boolean or numbers with this syntax.

on_...:
  - http_request.post:
      url: https://esphome.io
      json:
        key: !lambda |-
          return id(my_sensor).state;
        greeting: "Hello World"

    # Will send:
    # {"key": "42.0", "greeting": "Hello World"}

POST Body in JSON format (syntax 2)

Note: use this syntax to send boolean or numbers in JSON.

The JSON message will be constructed using the ArduinoJson library. In the json option you have access to a root object which represents the base object of the JSON message. You can assign values to keys by using the root["KEY_NAME"] = VALUE; syntax as shown below.

on_...:
  - http_request.post:
      url: https://esphome.io
      json: |-
        root["key"] = id(my_sensor).state;
        root["greeting"] = "Hello World";

    # Will send:
    # {"key": 42.0, "greeting": "Hello World"}

GET values from a JSON body response

If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is set to player_volume you can do this, but note that checking for the presence of the key will prevent difficult-to-read error messages:

This example assumes that the server returns a response as a JSON object similar to this: {"status":"play","vol":"42","mute":"0"}

If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is set to player_volume:

on_...:
- http_request.get:
    url: https://esphome.io
    capture_response: true
    on_response:
      then:
        - lambda: |-
            json::parse_json(body, [](JsonObject root) -> bool {
                if (root["vol"]) {
                    id(player_volume).publish_state(root["vol"]);
                    return true;
                }
                else {
                  ESP_LOGD(TAG,"No 'vol' key in this json!");
                  return false;
                }
            });

See Also