Issue reading HTTP request body from a JSON POST in PHP

Issue reading HTTP request body from a JSON POST in PHP

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoding JSON Payloads in PHP Webhooks

When a webhook fires, your server logs often tell the whole story of what is arriving at your endpoints. You might see headers like Content-Type: text/xml; charset=UTF-8 and a substantial Content-Length, yet the actual body content turns out to be a JSON object. This mismatch between header declarations and payload format is a common source of frustration when trying to parse the data in PHP using standard superglobals.

The immediate instinct is often to reach for $_POST. While this variable works perfectly for form-encoded data, it relies on PHP's built-in input parser to split the request body into key-value pairs based on boundaries or delimiters. When a client sends raw JSON, that parser fails to populate $_POST in any useful way. Accessing $_POST['json'] or iterating through $_POST will yield empty results because the data hasn't been transformed into an associative array; it remains a single, unprocessed string blob in the input stream.

This is where php://input becomes essential. PHP exposes a special stream wrapper that allows you to read the raw request body directly from the HTTP layer, bypassing any parsing logic entirely. You can use file_get_contents('php://input') or fopen('php://input', 'r') to retrieve this data. However, simply retrieving the string is only half the battle; you must still decode it into a usable structure using json_decode().

The critical detail often missed is the order of operations regarding headers. Many clients, including those running on older versions of Java or specific frameworks like Jakarta Commons-HttpClient, include a Content-Type header that indicates the media type (e.g., text/xml, application/json, or even just text/plain). If your application blindly trusts the Content-Type header to determine how to handle the input, you might attempt XML parsing on a JSON payload, leading to syntax errors. Conversely, if you rely solely on $_POST, you ignore the raw data entirely.

To handle this robustly, your webhook handler should explicitly read from php://input and then apply json_decode() regardless of the Content-Type header value, provided you are expecting JSON. Here is a practical pattern for doing so:

// Read the raw body from the input stream
$rawBody = file_get_contents('php://input');

// Decode the JSON string into an associative array or object
$data = json_decode($rawBody, true);

// Handle potential decoding errors gracefully
if (json_last_error() !== JSON_ERROR_NONE) {
    // Log the error or return a 400 Bad Request
    http_response_code(400);
    echo json_encode(['error' => 'Invalid JSON payload']);
    exit;
}

// Now $data is a standard PHP array ready for logic
// Example: $data['username']

This approach treats the incoming stream as opaque data until your application explicitly decodes it. It prevents assumptions about the Content-Type header from breaking your parsing logic. If the payload arrives as valid JSON but the client incorrectly labeled it, this method ensures you still capture and process the object correctly.

If you are using a framework like Laravel, the handling is slightly more abstracted. The Request object automatically reads php://input, but you must ensure you aren't accidentally switching to form parsing unless necessary. For custom scripts or microservices without PECL extensions, sticking to file_get_contents('php://input') remains the most portable and reliable method for accessing raw HTTP request bodies in PHP 5.x and above.

Always validate that the decoded data is indeed an array or object before attempting to access specific keys. A malformed JSON string will return null from json_decode(), and trying to access properties on null will trigger a fatal error. Checking json_last_error() provides immediate feedback on whether the payload was syntactically valid.

Our network