Webhook Testing in PHP

Basic PHP Webhook Handler

PHP webhook handlers are just plain PHP scripts. The key rule: call file_get_contents('php://input') as the very first operation — before json_decode() — to preserve the raw bytes for signature verification. Calling $_POST or json_decode() first does not destroy the stream in PHP, but consistently reading raw first is the safest habit.

<?php
// Read raw body before json_decode (required for HMAC)
$rawBody = file_get_contents('php://input');
$payload = json_decode($rawBody, true);

$eventType = $_SERVER['HTTP_X_EVENT_TYPE'] ?? '';

// Respond quickly
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['received' => true]);

HTTP headers arrive in $_SERVER with the prefix HTTP_, uppercased, and with hyphens replaced by underscores. So the header X-Event-Type becomes $_SERVER['HTTP_X_EVENT_TYPE'].

HMAC Signature Verification in PHP

PHP's built-in hash_hmac() and hash_equals() functions are everything you need. Use hash_equals() rather than === to prevent timing attacks:

<?php
function verifyWebhookSignature(string $rawBody, string $signature, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

$rawBody  = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';
$secret   = getenv('WEBHOOK_SECRET');

if (!verifyWebhookSignature($rawBody, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
// Process $payload...
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['received' => true]);

Async Processing in PHP

PHP is synchronous by default, but you can flush the response to the client while continuing to execute code. The output-buffering trick below sends the 200 and closes the connection before running your slow processing logic:

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

// Send the response immediately
http_response_code(200);
header('Content-Type: application/json');
header('Connection: close');
$body = json_encode(['received' => true]);
header('Content-Length: ' . strlen($body));
echo $body;

// Flush and close the connection
if (ob_get_level()) ob_end_flush();
flush();

// Now do slow work — the client has already received 200
ignore_user_abort(true);
processWebhookEvent($payload);

For production workloads, prefer pushing to a proper queue (Redis + a worker, SQS, or a job table in your database) rather than relying on the flush trick — it's fragile and depends on the web server respecting the flush. The output-buffer approach works well for low-traffic hooks or simple scripts.

Using Requex During Development

PHP development often runs on a local server (XAMPP, Laravel Valet, DDEV) that isn't publicly reachable. Instead of setting up a tunnel, point the webhook provider at a Requex.me endpoint first.

Requex captures the exact payload the provider sends — including all headers and the raw body. You can then replay that exact request against your local PHP script with curl:

curl -X POST http://localhost/webhook.php \
  -H "Content-Type: application/json" \
  -H "X-Signature-256: sha256=abc123..." \
  -d '{"id":"evt_123","type":"payment.succeeded"}'

This means you can iterate on your handler without triggering a real transaction in the provider each time.