How to sign and verify a message with HMAC-SHA256 in PHP

1<?php
2// Sender: HMAC-SHA256 over the exact body bytes, sent as "sha256=<hex>"
3function sign(string $secret, string $rawBody): string
4{
5    return 'sha256=' . hash_hmac('sha256', $rawBody, $secret); // data first, then the key
6}
7 
8// Receiver: recompute over the raw body and compare in constant time
9function verify(string $secret, string $rawBody, ?string $header): bool
10{
11    if ($header === null) {
12        return false; // a missing header fails, it never skips the check
13    }
14    return hash_equals(sign($secret, $rawBody), $header); // known value first, then the received one
15}
16 

1<?php
2require __DIR__ . '/webhook.php';
3 
4$secret = getenv('WEBHOOK_SECRET');
5$rawBody = file_get_contents('php://input'); // the bytes as received; $_POST stays empty for JSON
6$header = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? null; // how PHP names X-Hub-Signature-256
7 
8if ($secret === false || !verify($secret, $rawBody, $header)) {
9    http_response_code(401);
10    exit("bad signature\n");
11}
12$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
13echo "accepted {$event['action']} #{$event['number']}\n";
14 

How it works

1. hash_hmac('sha256', $rawBody, $secret) returns 64 lower-case hex digits (pass true as the fourth argument for raw bytes); the header value is sha256= followed by them.
2. hash_equals($known, $received) compares in constant time and returns false for strings of different lengths; the documented order is the value you computed first, the one you received second.
3. file_get_contents('php://input') returns the request body exactly as sent. PHP exposes the header as $_SERVER['HTTP_X_HUB_SIGNATURE_256']: upper-cased, dashes turned into underscores, prefixed with HTTP_.
4. The run checks GitHub's example (Hello, World!, secret It's a Secret to Everybody → sha256=757107ea…3e17), then serves the endpoint with php -S and posts real requests with curl.

Gotchas

• hash_hmac takes the data before the key. Swapped arguments produce a perfectly valid-looking MAC that never matches — the run prints it next to the right one.
• Never compare MACs with ==: two different strings that look like numbers in exponent notation compare equal ('0e1234' == '0e5678' is true in PHP 8.5). hash_equals compares the strings as they are, in constant time.
• The MAC covers bytes, not JSON: the same event minified is rejected with 401. Verify the php://input string before json_decode, never a re-encoded array.

Related recipes

• How to sign and verify a message with HMAC-SHA256 in Ruby
• How to sign and verify a message with HMAC-SHA256 in Python
• How to sign and verify a message with HMAC-SHA256 in Node.js
• How to sign and verify a message with HMAC-SHA256 with OpenSSL
• How to verify an ES256 JWT in PHP