HTTP Request

The http_request component lets you make HTTP/HTTPS requests.

Note

This component works only with arduino framework 2.5.0 or newer.

First, you need to setup a component:

# Example configuration entry
http_request:
  useragent: esphome/device
  timeout: 10s

Configuration variables:

  • useragent (Optional, string): User-Agent header for requests. Defaults to ESPHome.

  • timeout (Optional, time): Timeout for request. Defaults to 5s.

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

HTTP Request Actions

Component support 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
      verify_ssl: false
  # Short form
  - http_request.get: https://esphome.io

Configuration variables:

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

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

  • verify_ssl (Optional, boolean): Verify the SSL certificate of the endpoint. Defaults to true.

Note

Currently ESPHome can’t verify the SSL certificate of the endpoint. Set verify_ssl: false to make HTTPS request.

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
      verify_ssl: false
  # 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"
      verify_ssl: false

Configuration variables:

  • method (Required, string): HTTP method to use (GET, POST, PUT, DELETE, PATCH).

  • All other options from http_request.post Action.

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;

Body in JSON format (syntax 1)

Note: all values of the map should be a strings. It’s impossible to send boolean or numbers with this syntax.

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

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

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 will represents the base object of the JSON message. You can assign values to keys by using the root["KEY_NAME"] = VALUE; syntax as seen below.

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

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