Receive and Decode JSON POST Requests in PHP

You will learn the difference between form POST fields and a JSON request body in PHP. You will be able to read JSON from php://input, decode it safely, diagnose invalid payloads, and apply the pattern to payment webhooks and APIs.

$_POST is a PHP superglobal containing parsed form fields. PHP fills it automatically when a request uses a form-oriented content type such as:

• application/x-www-form-urlencoded
• multipart/form-data

A JSON API or webhook usually sends this header instead:

Content-Type: application/json

In that case, the data is sent as the raw HTTP request body. PHP does not automatically turn JSON into $_POST, so you must read the body yourself and decode it.

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);

php://input is a read-only PHP stream that provides the raw request body. json_decode() converts the JSON text into a PHP value.

This matters because many modern systems communicate with JSON: REST APIs, JavaScript front ends, mobile apps, and payment-provider webhooks. Reading the correct input source is the first step before validation and business logic.

Think of an HTTP request as a delivery package:

• The headers are the label describing the package contents.
• The body is the item inside the package.
• $_POST is a PHP assistant trained to unpack HTML form packages.
• JSON is a different kind of package, so the assistant leaves it intact in php://input.

You read the package yourself, then use json_decode() as a translator from JSON text into PHP arrays and values.

Read the raw body, decode it, and check whether decoding succeeded:

<?php
header('Content-Type: application/json');

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    echo json_encode([
        'error' => 'Invalid JSON: ' . json_last_error_msg(),
    ]);
    exit;
}

$name = $data['name'] ?? 'Guest';

echo json_encode([
    'message' => "Hello, {$name}",
]);

If the client sends:

{
  "name": "Amina",
  "amount": 49.99
}

then $data becomes this PHP associative array:

[
    'name' => 'Amina',
    'amount' => 49.99,
]

The second argument, true, tells json_decode() to create associative arrays. Without it, JSON objects become PHP stdClass objects and properties are accessed with -> instead of array brackets.

Consider this endpoint:

<?php
$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);

$status = $data['status'] ?? 'unknown';
echo $status;

Given this request body:

{"status":"paid","invoice_id":"INV-1042"}

Execution proceeds as follows:

1. file_get_contents('php://input') reads the exact request body as a string.

   $rawBody === '{"status":"paid","invoice_id":"INV-1042"}'
   

2. json_decode($rawBody, true) parses that JSON string into an associative array.

   $data === [
       'status' => 'paid',
       'invoice_id' => 'INV-1042',
   ]
   

3. $data['status'] ?? 'unknown' gets the status when present. If it is missing, it safely uses 'unknown'.

4. echo $status outputs:

   paid
   

For debugging, use var_dump($data) or print_r($data, true). Do not use echo $_POST, because an array cannot be displayed as ordinary text.

Common places where PHP receives JSON request bodies include:

• Payment webhooks: A provider notifies your server that an invoice was paid, refunded, or failed.
• REST API endpoints: A mobile app sends profile updates such as {"email":"user@example.com"}.
• JavaScript front ends: fetch() sends JSON to a PHP backend.
• Internal services: One service posts order or inventory events to another.
• Command-line integrations: Automation tools call an HTTP endpoint with JSON configuration or event data.

For a payment webhook, decoding JSON is only one part of the task. You should also verify the provider's signature, validate expected fields, and make processing safe to repeat because providers may resend events.

A production endpoint normally separates input handling from payment logic and rejects invalid requests early.

<?php
function readJsonBody(): array
{
    $rawBody = file_get_contents('php://input');

    try {
        $data = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    } catch (JsonException $exception) {
        http_response_code(400);
        echo json_encode(['error' => 'Request body must contain valid JSON.']);
        exit;
    }

    if (!is_array($data)) {
        http_response_code(400);
        echo json_encode(['error' => 'JSON body must be an object.']);
        exit;
    }

    return $data;
}

$event = readJsonBody();
$eventType = $event['type'] ?? null;

if ($eventType === null) {
    http_response_code(422);
    echo json_encode(['error' => 'Missing event type.']);
    exit;
}

// Verify the payment provider signature using the raw body before trusting $event.
// Process the event only after verification.
http_response_code(200);
echo json_encode(['received' => true]);

Useful project patterns:

• Guard clauses: Stop immediately when JSON is invalid or required data is absent.
• Validation: Check types and allowed values before using values in database queries or payment logic.
• Raw-body preservation: Keep $rawBody for webhook signature verification. A signature is commonly calculated from the original bytes, not from re-encoded PHP data.
• Clear responses: Return appropriate HTTP status codes such as 400 for malformed JSON and 422 for valid JSON with invalid fields.
• Idempotency: Store processed event IDs so a retry does not charge or update an order twice.

Echoing an array

This produces the word Array and may emit an "Array to string conversion" warning:

// Incorrect for inspecting array contents
echo $_POST;

Use one of these while debugging:

var_dump($_POST);
print_r($_POST);
echo json_encode($_POST, JSON_PRETTY_PRINT);

Expecting JSON in $_POST

// Usually null when Content-Type is application/json
$amount = $_POST['amount'];

Instead, decode the raw body:

$data = json_decode(file_get_contents('php://input'), true);
$amount = $data['amount'] ?? null;

Skipping JSON error handling

$data = json_decode($rawBody, true);
// $data can be null because the JSON is invalid.

Check json_last_error() or use JSON_THROW_ON_ERROR.

Reading php://input too late or repeatedly

Read the body once near the start of the endpoint and store it in $rawBody. This is especially important when the same raw text is needed for webhook signature verification.

Trusting a payment callback without verification

A request reaching your endpoint does not prove it came from the payment provider. Follow that provider's documentation to verify its signature or secret, and validate the event before changing an order status.

Assuming a successful provider log means PHP decoded the data

A provider log can confirm delivery, but PHP still needs the correct Content-Type, raw-body reading, valid JSON, and endpoint configuration to process the request.

json_decode() also has two common output styles:

Both are valid. Associative arrays are often convenient for request validation, but choose one style and use it consistently.

// Read the JSON request body once
$rawBody = file_get_contents('php://input');

// Decode to an associative array
$data = json_decode($rawBody, true);

// Check for parsing errors
if (json_last_error() !== JSON_ERROR_NONE) {
    $message = json_last_error_msg();
}

// Or throw an exception on invalid JSON
$data = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);

// Safely read an optional field
$email = $data['email'] ?? null;

// Debug an array
var_dump($data);
print_r($data);

// Return JSON
header('Content-Type: application/json');
echo json_encode(['ok' => true]);

Rules to remember:

• JSON sent with Content-Type: application/json is normally not placed in $_POST.
• echo cannot meaningfully display an array; use var_dump() or print_r().
• Validate decoded data before using it.
• Keep the original raw body when verifying webhook signatures.
• Never rely on a Content-Type header alone as a security check.

Why does echo $_POST print Array in PHP?

$_POST is an array. echo outputs strings, not an array's contents. Use var_dump($_POST) or print_r($_POST) to inspect it.

Why is $_POST empty when I send JSON?

PHP automatically populates $_POST for form-encoded requests, not for a JSON body with Content-Type: application/json. Read php://input and decode it.

How do I read JSON POST data in PHP?

$data = json_decode(file_get_contents('php://input'), true);

Then check for JSON errors before relying on $data.

Should I use $_REQUEST for JSON data?

No. $_REQUEST combines query, form, and cookie values based on configuration; it does not solve JSON body parsing and can make input sources unclear.

What does the true argument in json_decode() do?

It converts JSON objects into associative arrays. Without true, JSON objects become stdClass objects.

How can I tell whether the sender provided invalid JSON?

Use json_last_error() and json_last_error_msg(), or use JSON_THROW_ON_ERROR and catch JsonException.

Is decoding JSON enough for a payment webhook?

No. Also verify the payment provider's signature, validate fields, handle duplicate events safely, and use HTTPS.

• PHP superglobals ($_GET, $_POST, $_FILES) — Understand where PHP places different kinds of request data.
• HTTP request headers and content types — The Content-Type header describes how a request body is formatted.
• JSON encoding and decoding in PHP — Learn json_encode(), json_decode(), and JSON error handling.
• PHP arrays and stdClass objects — These are the two common structures created by json_decode().
• Input validation — Decoded input must be checked for required fields, types, and allowed values.
• REST APIs in PHP — JSON request and response handling is fundamental to API endpoints.
• Webhook signature verification — Essential for confirming payment and third-party webhook requests are authentic.
• HTTP status codes — Use status codes to report malformed or invalid requests clearly.