Why is $_POST empty when a payment provider posts a JSON webhook to a PHP endpoint, and how do you read that body?

## Why $_POST is empty Before a script runs, PHP decides whether to parse the request body. It does so only when: 1. `enable_post_data_reading` is On (the default); 2. the request has a `Content-Type`; 3. the method is exactly `POST`. Even then, only two content types are turned into `$_POST`: `application/x-www-form-urlencoded` and `multipart/form-data`. A payment provider's webhook arrives as `POST` with `Content-Type: application/json`, so PHP reads the body but has no parser for it: `$_POST` is `[]`. Nothing is wrong with the request; PHP simply does not decode JSON automatically. ## php://input `php://input` is a **read-only stream** that yields the raw request body exactly as the client sent it. - `file_get_contents('php://input')` reads it all into a string, which suits bodies of a few kilobytes such as webhooks. - `fopen('php://input', 'rb')` gives a stream you can read in chunks for large bodies. - PHP keeps the body in a temporary stream, so opening `php://input` a second time in the same request starts again from the beginning. - It is **not available** for a `multipart/form-data` POST while `enable_post_data_reading` is On, because PHP has already consumed that body to build `$_POST` and `$_FILES`. ## A webhook handler step by step 1. **Method**: accept only `$_SERVER['REQUEST_METHOD'] === 'POST'`; answer anything else with 405. 2. **Content type**: check `$_SERVER['CONTENT_TYPE']`. It has no `HTTP_` prefix, because the CGI convention passes the body's type and length as `CONTENT_TYPE` and `CONTENT_LENGTH`. It may carry parameters, such as `application/json; charset=utf-8`, so compare the part before `;`. 3. **Raw body**: `$raw = file_get_contents('php://input');`. 4. **Signature**: providers typically sign the raw body with a shared secret and send the result in a header. Recompute it with `hash_hmac('sha256', $raw, $secret)` and compare with `hash_equals()`, which takes time independent of where the strings differ. 5. **Decode**: only after the signature matches, `json_decode($raw, true, 512, JSON_THROW_ON_ERROR)`. 6. **Respond quickly**: acknowledge with a 2xx status and do slow work later, since providers retry deliveries that time out. The signature must be checked on the **raw string**. Decoding and re-encoding changes whitespace, key order and number formatting, so a signature computed over `json_encode(json_decode($raw))` will not match what the provider signed. ## Pitfalls | Mistake | Effect | |---|---| | Reading `$_POST['event']` | Always `null` for a JSON body | | Decoding before verifying | Parsing attacker-controlled input before knowing who sent it | | Comparing signatures with `==` or `===` | Comparison time can leak how many leading characters matched | | Looking for `$_SERVER['HTTP_CONTENT_TYPE']` | Not reliably set; `CONTENT_TYPE` is the dependable key | | Treating an empty body as a JSON error | `file_get_contents()` returns `''`, which `json_decode()` with `JSON_THROW_ON_ERROR` rejects — reply 400, not 500 | ## Large bodies `file_get_contents('php://input')` loads the whole body into memory, which is fine for webhooks of a few kilobytes. For large uploads of raw data, open the stream and process it in chunks instead: ```php $in = fopen('php://input', 'rb'); while (!feof($in)) { $chunk = fread($in, 8192); // hash, forward or write the chunk } fclose($in); ``` Incremental hashing with `hash_init()` and `hash_update()` lets a signature be computed over a body that is never held in memory at once. ## Trying it locally PHP's built-in development server is enough to exercise a webhook endpoint: start it with `php -S localhost:8000` in the project directory, then post a JSON body with any HTTP client, setting the `Content-Type` and signature headers by hand. Test the failure paths too — a wrong signature, an empty body and a non-JSON content type should each produce a 4xx response, not a 500. ## Where header values come from The provider's signature header arrives in `$_SERVER` like any other header: `HTTP_` followed by its name in upper case with hyphens as underscores, so a header named `X-Signature` is `$_SERVER['HTTP_X_SIGNATURE']`. Like every `HTTP_*` value it is client-supplied — which is exactly why it is compared against a value you compute yourself rather than believed.