Understanding How Your ESP32 Sends the HTTP POST Request

Home / References / ESP32 Library / HTTPClient

Introduction: A Deeper Look at ESP32 Web Communication

Welcome! This page expands on the example code presented in our main reference about the ESP32 HTTPClient Library’s POST method on AvantMaker.com. If you’ve ever wondered exactly *what* your ESP32 sends to a web server when you use the `POST()` method, you’re in the right place.

Understanding the structure of these web requests is crucial for anyone building connected projects. It helps you troubleshoot issues when things don’t work as expected, design more efficient communication protocols for your IoT devices, and interact correctly with various web services and APIs. By breaking down a real example, we aim to demystify the process of sending data from your ESP32 out to the web using the standard language of the internet: HTTP.

The Example Code: Sending Data with an Arduino Sketch

Let’s start with the Arduino sketch running on the ESP32. This code connects your ESP32 board to a Wi-Fi network and then repeatedly sends a small packet of data to a public test server, `httpbin.org`, using an HTTP POST request.

Here’s the code:

/*
 * Author: Avant Maker
 * Date: February 21, 2025
 * Version: 1.0
 * Description: This example code demonstrates how to 
 * use the ESP32 HTTPClient Library's POST to send data 
 * to https://httpbin.org/post. 
 * The httpbin.org service is a free tool designed for testing 
 * HTTP requests—it accepts your POST data and responds with a
 * JSON object containing what you sent. 
 *
 * License: MIT 
 * 
 * Code Source: This example code is sourced from the Comprehensive 
 * Guide to the ESP32 Arduino Core Library, accessible on 
 * AvantMaker.com. For additional code examples and in-depth 
 * documentation related to the ESP32 Arduino Core Library, 
 * please visit:
 *
 * https://avantmaker.com/references/esp32-arduino-core-index/
 *
 * AvantMaker.com, your premier destination for all things 
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated 
 * to empowering makers, learners, and enthusiasts with the resources
 * they need to bring their innovative ideas to life.
 */

#include <WiFi.h>
#include <HTTPClient.h>

const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);

    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("Connected to WiFi");
}

void loop() {
    if (WiFi.status() == WL_CONNECTED) {
        HTTPClient http;
        http.begin("https://httpbin.org/post"); // Real public endpoint
        http.addHeader("Content-Type", "application/x-www-form-urlencoded");

        // Simple key-value data to send
        String postData = "device=ESP32&user=AvantMaker";
        int httpCode = http.POST(postData);

        if (httpCode > 0) {
            Serial.printf("HTTP Response Code: %d\n", httpCode);
            if (httpCode == HTTP_CODE_OK) { // 200
                String response = http.getString();
                Serial.println("Server Response:");
                Serial.println(response);
            }
        } else {
            Serial.printf("POST failed, error: %s\n", http.errorToString(httpCode).c_str());
        }
        http.end();
    }
    delay(20000); // Send POST every 20 seconds
}

How to Use This Code:

1. Replace `”your_SSID”` and `”your_PASSWORD”` with your actual Wi-Fi network name and password.
2. Upload this sketch to your ESP32 board using the Arduino IDE.
3. Open the Serial Monitor (set to 115200 baud).
4. Once connected to Wi-Fi, the ESP32 will send a POST request every 20 seconds, and you’ll see the server’s response printed in the Serial Monitor.

This code demonstrates the ESP32 HTTPClient Library’s POST() method to send data to a server. It connects to a Wi-Fi network and sends an HTTP POST request with key-value data (“device=ESP32&user=AvantMaker”) to a public endpoint. The response from the server is then printed to the Serial Monitor, showing how to handle the result of the POST() call.

The key parts related to the POST request are

• creating the `HTTPClient` object
• specifying the URL with `http.begin()`
• adding the `Content-Type` header with `http.addHeader()`
• defining the data payload in `postData`
• and finally sending it using `http.POST(postData)`.

Anatomy of the HTTP POST Request Generated by the ESP32

When the `http.POST(postData)` line in the sketch executes, the ESP32 (using the `HTTPClient` library) constructs and sends an HTTP request over the network. Based on the sketch and the standard behavior of the library, the raw request sent to `httpbin.org` looks like this:

POST /post HTTP/1.1
Host: httpbin.org
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept-Encoding: identity;q=1,chunked;q=0.1,*;q=0
User-Agent: ESP32HTTPClient

device=ESP32&user=AvantMaker

Let’s break this down line by line:

• POST /post HTTP/1.1:
  This is the request line.
  • POST: This is the HTTP method (or verb). POST is used to send data to a server to create or update a resource. In simple terms, it means “Here’s some data for you to process.”
  • /post: This is the path on the server we are sending the request to. It’s appended to the host name (`httpbin.org`) to form the full URL (`httpbin.org/post`).
  • HTTP/1.1: This indicates the version of the HTTP protocol being used.
• Host: httpbin.org:
  This header is required in HTTP/1.1 and specifies the domain name of the server we are contacting.
• Content-Type: application/x-www-form-urlencoded:
  This crucial header tells the server how the data in the body of the request is formatted. application/x-www-form-urlencoded is a standard format used when submitting simple web forms. It means the data is structured as key-value pairs (like `key1=value1`), with pairs separated by an ampersand (`&`). This directly corresponds to the `http.addHeader(“Content-Type”, …)` line in our sketch.
• Content-Length: 28:
  This header tells the server the size of the data payload (the body of the request) in bytes. The string `device=ESP32&user=AvantMaker` is exactly 28 characters long. The `HTTPClient` library calculates this automatically before sending the request.
• Accept-Encoding: identity;q=1,chunked;q=0.1,*;q=0:
  This header tells the server what kind of content encoding (like compression) the client (ESP32) can understand in the response. The library adds this automatically.
  • identity;q=1: Indicates that the client prefers content to be sent without any encoding (identity means no compression). The priority is set to 1, which is the highest value.
  • chunked;q=0.1: Indicates that the client can accept chunked transfer encoding, but with a very low priority (q=0.1).
  • *;q=0: Indicates that the client does not accept any other encoding methods (* represents all other encodings), as the priority is set to 0.
• User-Agent: ESP32HTTPClient:
  This header identifies the client software making the request. The ESP32 `HTTPClient` library uses “ESP32HTTPClient” by default.
• (Blank Line):
  A blank line is essential in HTTP. It separates the headers (metadata about the request) from the body (the actual data being sent).
• device=ESP32&user=AvantMaker:
  This is the request body or payload. It’s the actual data being sent, formatted according to the `Content-Type` header. This data comes directly from the `postData` string variable in our Arduino sketch. It consists of two key-value pairs:
  • device=ESP32: Identifies the device as an ESP32.
• • user=AvantMaker: Identifies the user as “AvantMaker”.
  According to the `Content-Type` header, The data is URL-encoded, meaning special characters are replaced with %XX sequences if necessary (though no special characters are present in this example).

What the Server Said Back: Analyzing the Response from httpbin.org

After the ESP32 sends the request, the `httpbin.org/post` service processes it and sends back a response. The Arduino sketch receives this response and prints it to the Serial Monitor. Here’s the response you saw:

Let’s look at the key parts of this response:

HTTP Response Code: 200
Server Response:
{
   "args": {}, 
   "data": "", 
   "files": {}, 
   "form": {
     "device": "ESP32", 
     "user": "AvantMaker"
   },
   "headers": {
     "Accept-Encoding": "identity;q=1,chunked;q=0.1,*;q=0", 
     "Content-Length": "28", 
     "Content-Type": "application/x-www-form-urlencoded", 
     "Host": "httpbin.org", 
     "User-Agent": "ESP32HTTPClient", 
     "X-Amzn-Trace-Id": "Root=1-67eba05e-6c3ad1bb27bf19ee56b90d66"
   }, 
   "json": null, 
   "origin": "11.22.33.44", 
   "url": "https://httpbin.org/post"
}

• HTTP Response Code: 200:
  This is printed by our sketch (`Serial.printf(“HTTP Response Code: %d\n”, httpCode);`). A code of 200 means “OK” – the server successfully received and understood the request.
• Server Response: {...}:
  This is the body of the server’s response, printed by `Serial.println(response);`. Since `httpbin.org` is a testing tool, its response is designed to reflect the request it received back to the sender. The body is formatted in JSON (JavaScript Object Notation), a common data format used in web communication.
• "args": {}:
  An object containing the URL query string parameters sent with the request. It’s empty ({}) because the ESP32 requested /post without any parameters appended (e.g., ?key=value).
• "data": "":
  This field would contain the raw request body *if* the `Content-Type` was something else (like `text/plain` or `application/json`). Since it was form data, it’s parsed into the `form` field instead.
• "files": {}:
  An object containing any files uploaded via a multipart/form-data request. It’s empty ({}) because the ESP32 sent URL-encoded form data, not files.
• "form": { "device": "ESP32", "user": "AvantMaker" }:
  This is the most important part of the response for confirming our POST request worked. The server correctly interpreted the request body (device=ESP32&user=AvantMaker) because the `Content-Type` was `application/x-www-form-urlencoded`. It parsed the data into key-value pairs and shows them within the `form` field. This confirms our data arrived and was understood.
• "headers": { ... }:
  This section shows the headers that the server received from our ESP32 client. You can see `Content-Length: 28`, `Content-Type: application/x-www-form-urlencoded`, `Host: httpbin.org`, and `User-Agent: ESP32HTTPClient`, matching what we examined in the request data structure.
• "origin": "11.22.33.44":
  This shows the public IP address from which the request originated (your ESP32’s IP address as seen by the server).
• "url": "https://httpbin.org/post":
  Confirms the URL that was requested.

Conclusion: Building Connected Projects with Confidence

Understanding the structure of an HTTP POST request—the request line, the headers like `Content-Type` and `Content-Length`, and the formatted data body—is fundamental when working with connected devices like the ESP32. It allows you to send data effectively to web servers and APIs, interact with online services, and debug communication problems.

We hope this breakdown helps clarify what happens behind the scenes when your ESP32 code calls `http.POST()`. To continue your exploration of the ESP32’s capabilities, be sure to check out the AvantMaker ESP32 Resources Hub, where we’ve crafted a comprehensive collection of Reference and Tutorial materials for the ESP32.

Happy Making!