Why WhatsApp webhook signature verification fails: the raw body trap

You set up your WhatsApp Cloud API webhook.

You implemented the GET verification endpoint. Meta hit your server with hub.mode=subscribe and hub.challenge, your code returned the challenge, and the Meta App Dashboard turned a satisfying shade of green.

Then a customer sent a message.

Meta dispatched a POST request to your webhook URL. Your application attempted to verify the X-Hub-Signature-256 header against your App Secret.

And the hash did not match. The signature verification threw an exception, returned a 403 Forbidden, and Meta temporarily paused your webhook for failing health checks.

This is the most common bug developers hit when implementing Meta webhooks. It is almost never a bug in your crypto logic. It is caused by what happens to the HTTP request body before your code touches it.

Here is what breaks, why it happens, and how to fix it in 5 minutes.

The Two Meta Webhook Handshakes

Meta uses two completely different verification mechanisms:

1. The Verification Handshake (GET)

When configuring the webhook in the Meta App Dashboard, Meta sends a GET request:

GET /webhook?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=my_secret_token

You check if hub.verify_token matches your chosen string, and echo back hub.challenge in plain text with a 200 OK.

This only tests that you own the URL. It does not secure subsequent messages.

2. The Message Signature (POST)

When a real message arrives, Meta sends a POST request with JSON in the body and a cryptographic signature in the header:

X-Hub-Signature-256: sha256=d6a74b123...
Content-Type: application/json

Meta calculates this signature by running an HMAC-SHA256 over the raw HTTP request body using your Meta App Secret as the key.

Your application must compute the identical hash and verify they match:

$$\text{hash} = \text{HMAC-SHA256}(\text{raw_body}, \text{APP_SECRET})$$

The Trap: Re-encoded JSON Is Not the Raw Body

In modern frameworks like Laravel, Express, Django, or NestJS, HTTP requests pass through input-parsing middleware before reaching your controller.

A developer will often write something like this:

// ❌ WRONG: This will fail verification
$payload = $request->all(); // or $request->json()->all()
$calculatedHash = hash_hmac('sha256', json_encode($payload), $appSecret);

Or in Node / Express:

// ❌ WRONG: JSON.stringify does not reconstruct the original wire bytes
const calculatedHash = crypto
  .createHmac('sha256', appSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

Why this fails 100% of the time

A cryptographic hash is sensitive to the exact byte sequence.

When your framework parses incoming JSON into an associative array or object, it strips whitespace, normalizes Unicode escapes, and may reorder dictionary keys.

When you call json_encode($payload) or JSON.stringify(req.body), the re-serialized JSON string:

• May have different whitespace (e.g. {"key":"val"} vs {"key": "val"})
• May escape slashes differently (e.g. \/ vs /)
• May alter key ordering (e.g. b before a)

Even a single shifted space character changes every byte in the resulting SHA-256 hash. The signatures will never match.

The Fix: Read the Unparsed Raw Stream

You must capture the raw, un-parsed byte stream directly from the HTTP input buffer.

In Laravel / PHP:

Use $request->getContent():

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;

class VerifyMetaSignature
{
    public function handle(Request $request, Closure $next)
    {
        $signature = $request->header('X-Hub-Signature-256');

        if (! $signature || ! str_starts_with($signature, 'sha256=')) {
            throw new AccessDeniedHttpException('Missing or invalid signature header.');
        }

        $expectedHash = substr($signature, 7); // strip 'sha256='
        $appSecret = config('services.meta.app_secret');

        // MUST use getContent() — the raw bytes before JSON parsing
        $rawPayload = $request->getContent();

        $calculatedHash = hash_hmac('sha256', $rawPayload, $appSecret);

        // Constant-time comparison to prevent timing attacks
        if (! hash_equals($expectedHash, $calculatedHash)) {
            throw new AccessDeniedHttpException('Invalid webhook signature.');
        }

        return $next($request);
    }
}

Warning for PHP: Do not use file_get_contents('php://input') if another middleware or logging package has already consumed the stream in a non-rewindable way. Laravel's $request->getContent() caches the raw string safely in memory for the lifecycle of the request.

In Express / Node.js:

By default, express.json() consumes the stream and discards the raw bytes. Use the verify option to preserve the raw buffer:

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json({
  verify: (req, res, buf, encoding) => {
    // Stash the raw buffer onto the request object
    req.rawBody = buf.toString(encoding || 'utf8');
  }
}));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  if (!signature) return res.sendStatus(401);

  const [prefix, expectedHash] = signature.split('=');
  const appSecret = process.env.META_APP_SECRET;

  const hmac = crypto.createHmac('sha256', appSecret);
  const calculatedHash = hmac.update(req.rawBody).digest('hex');

  // Timing-safe comparison
  const isValid = crypto.timingSafeEqual(
    Buffer.from(expectedHash, 'hex'),
    Buffer.from(calculatedHash, 'hex')
  );

  if (!isValid) return res.sendStatus(403);

  // Process verified payload
  res.sendStatus(200);
});

Two Other Traps to Check

If you are reading the raw payload and verification still fails:

1. Wrong Secret Key

Make sure you are using your Meta App Secret (found in App Dashboard → App Settings → Basic), NOT your Webhook Verify Token and NOT your WhatsApp Permanent Access Token.

The Verify Token is only for the GET handshake. The signature uses the App Secret.

2. Reverse Proxy / Cloudflare Truncation or Modification

If your application sits behind Cloudflare, Nginx, or an AWS Application Load Balancer:

• Ensure the proxy is not decompressing or modifying request bodies.
• Ensure the X-Hub-Signature-256 header is not being stripped by an over-eager Web Application Firewall (WAF) rule.

Once you switch to verifying the unparsed raw request content, signature validation becomes 100% deterministic, cryptographic errors vanish, and your webhook endpoint stays bulletproof.