{"id":505,"date":"2026-10-28T16:04:36","date_gmt":"2026-10-28T16:04:36","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/whatsapp-webhook-signature-validation\/"},"modified":"2026-10-28T16:04:50","modified_gmt":"2026-10-28T16:04:50","slug":"whatsapp-webhook-signature-validation","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/whatsapp-webhook-signature-validation\/","title":{"rendered":"How to validate the WhatsApp webhook signature (X-Hub-Signature-256)"},"content":{"rendered":"\n

Updated on October 28, 2026<\/em><\/p>\n\n\n\n

To validate a WhatsApp webhook signature, compute an HMAC SHA-256 of the request body using your Meta app secret<\/strong> as the key, then compare it with the X-Hub-Signature-256<\/code> header, which arrives as sha256=<hash><\/code>. If they match, the event came from Meta and was not tampered with. The mistake that breaks validation most often is hashing the JSON your framework already parsed instead of the exact bytes that arrived.<\/p>\n\n\n\n

This guide walks through the steps, ready-to-use code for Node.js (Express), Python (FastAPI and Flask) and PHP, and the most common pitfalls. For the bigger picture of the platform, see our WhatsApp Cloud API guide<\/a>.<\/p>\n\n\n\n

Why validate the signature<\/h2>\n\n\n\n

Your webhook URL is public. Anyone who finds it can send a POST<\/code> with JSON shaped like Meta’s, faking a customer message, a button reply that confirms a payment, or a delivered<\/code> status that never happened. Without validation, your system accepts all of it.<\/p>\n\n\n\n

Meta’s Graph API webhooks documentation<\/a> says every event notification is signed with SHA-256 and the signature is sent in the X-Hub-Signature-256<\/code> header, prefixed with sha256=<\/code>. Validation is optional, but Meta recommends it. In practice, it is what separates a trustworthy webhook from an open endpoint.<\/p>\n\n\n\n

The two requests your endpoint receives<\/h2>\n\n\n\n

The same URL receives two kinds of calls, each with its own check:<\/p>\n\n\n\n

Request<\/th>When it happens<\/th>What to check<\/th>Response<\/th><\/tr><\/thead>
Verification GET<\/code><\/td>When you set or change the URL in the app dashboard<\/td>hub.mode<\/code> equals subscribe<\/code> and hub.verify_token<\/code> matches the token you configured<\/td>200<\/code> with the hub.challenge<\/code> value<\/td><\/tr>
Event POST<\/code><\/td>Every message, status or account change<\/td>X-Hub-Signature-256<\/code> against the HMAC of the raw body<\/td>Fast 200<\/code>; process in a queue<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

According to Create a webhook endpoint<\/a>, a valid verification request gets a 200<\/code> with hub.challenge<\/code>; an invalid one gets anything other than 200<\/code> (a 403, for example). The same page requires a valid TLS certificate on the endpoint: self-signed certificates are not supported.<\/p>\n\n\n\n

The verify token<\/em> and the app secret<\/em> are different things. The verify token is a string you make up and enter in the dashboard; it only matters for the GET<\/code>. The app secret is generated by Meta, lives under App settings > Basic<\/strong>, and is what signs the POST<\/code> requests.<\/p>\n\n\n\n

Step-by-step validation<\/h2>\n\n\n\n
    \n
  1. Read the request body as bytes<\/strong>, before any JSON parser touches it.<\/li>\n\n\n
  2. Compute HMAC-SHA256(key = app secret, message = raw body)<\/code> and hex-encode it.<\/li>\n\n\n
  3. Build sha256=<\/code> + hash and compare it with the X-Hub-Signature-256<\/code> header using a constant-time comparison.<\/li>\n\n\n
  4. If it does not match, return 401 or 403 and drop the event.<\/li>\n\n\n
  5. If it matches, parse the JSON, queue the event and return 200<\/code>.<\/li>\n\n<\/ol>\n\n\n\n

    Constant-time comparison (crypto.timingSafeEqual<\/code>, hmac.compare_digest<\/code>, hash_equals<\/code>) keeps an attacker from guessing the hash byte by byte by measuring response times.<\/p>\n\n\n\n

    Node.js example with Express<\/h2>\n\n\n\n

    The key is express.raw()<\/code> on the webhook route, so req.body<\/code> is a Buffer<\/code> with the original bytes:<\/p>\n\n\n\n

    import express from 'express';\nimport crypto from 'node:crypto';\n\nconst app = express();\nconst APP_SECRET = process.env.META_APP_SECRET;\nconst VERIFY_TOKEN = process.env.WEBHOOK_VERIFY_TOKEN;\n\n\/\/ Verification GET\napp.get('\/webhook', (req, res) => {\n  const mode = req.query['hub.mode'];\n  const token = req.query['hub.verify_token'];\n  const challenge = req.query['hub.challenge'];\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) {\n    return res.status(200).send(challenge);\n  }\n  return res.sendStatus(403);\n});\n\n\/\/ Event POST: raw body on this route only\napp.post('\/webhook', express.raw({ type: 'application\/json' }), (req, res) => {\n  const received = req.get('X-Hub-Signature-256') || '';\n  const expected = 'sha256=' + crypto\n    .createHmac('sha256', APP_SECRET)\n    .update(req.body)\n    .digest('hex');\n\n  const a = Buffer.from(received);\n  const b = Buffer.from(expected);\n  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {\n    return res.sendStatus(401);\n  }\n\n  const event = JSON.parse(req.body.toString('utf8'));\n  res.sendStatus(200);\n  eventQueue.push(event); \/\/ process outside the request cycle\n});\n\napp.use(express.json()); \/\/ other routes can parse JSON as usual\napp.listen(3000);<\/code><\/pre>\n\n\n\n
    If your app already registers app.use(express.json())<\/code> before this route, the body arrives parsed and the hash will not match. Either declare the webhook route before the global middleware, or keep the raw bytes inside express.json<\/code> itself:<\/p>\n\n\n\n
    app.use(express.json({\n  verify: (req, _res, buf) => { req.rawBody = buf; },\n}));\n\/\/ then pass req.rawBody to createHmac<\/code><\/pre>\n\n\n\n
    Python example with FastAPI<\/h2>\n\n\n\n
    In FastAPI, await request.body()<\/code> returns the exact bytes. Do not sign the Pydantic model of the body:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport json\nimport os\n\nfrom fastapi import FastAPI, HTTPException, Request, Response\n\napp = FastAPI()\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\nVERIFY_TOKEN = os.environ[\"WEBHOOK_VERIFY_TOKEN\"]\n\n\n@app.get(\"\/webhook\")\nasync def verify(request: Request):\n    p = request.query_params\n    if p.get(\"hub.mode\") == \"subscribe\" and p.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return Response(content=p.get(\"hub.challenge\", \"\"), media_type=\"text\/plain\")\n    raise HTTPException(status_code=403)\n\n\n@app.post(\"\/webhook\")\nasync def receive(request: Request):\n    body = await request.body()\n    received = request.headers.get(\"x-hub-signature-256\", \"\")\n    expected = \"sha256=\" + hmac.new(APP_SECRET, body, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(received, expected):\n        raise HTTPException(status_code=401)\n\n    event = json.loads(body)\n    # enqueue the event and respond quickly\n    return {\"ok\": True}<\/code><\/pre>\n\n\n\n
    Python example with Flask<\/h2>\n\n\n\n
    In Flask, use request.get_data()<\/code>, which returns the raw body:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport os\n\nfrom flask import Flask, abort, request\n\napp = Flask(__name__)\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\n\n\n@app.post(\"\/webhook\")\ndef receive():\n    body = request.get_data()\n    received = request.headers.get(\"X-Hub-Signature-256\", \"\")\n    expected = \"sha256=\" + hmac.new(APP_SECRET, body, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(received, expected):\n        abort(401)\n    event = request.get_json()\n    return \"\", 200<\/code><\/pre>\n\n\n\n
    PHP example<\/h2>\n\n\n\n
    In PHP, the raw body comes from php:\/\/input<\/code>. Watch the GET<\/code>: PHP replaces dots with underscores in parameter names, so hub.verify_token<\/code> becomes $_GET['hub_verify_token']<\/code>.<\/p>\n\n\n\n
    <?php\n$appSecret = getenv('META_APP_SECRET');\n$verifyToken = getenv('WEBHOOK_VERIFY_TOKEN');\n\nif ($_SERVER['REQUEST_METHOD'] === 'GET') {\n    if (($_GET['hub_mode'] ?? '') === 'subscribe'\n        && hash_equals($verifyToken, $_GET['hub_verify_token'] ?? '')) {\n        echo $_GET['hub_challenge'] ?? '';\n        exit;\n    }\n    http_response_code(403);\n    exit;\n}\n\n$body = file_get_contents('php:\/\/input');\n$received = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';\n$expected = 'sha256=' . hash_hmac('sha256', $body, $appSecret);\n\nif (!hash_equals($expected, $received)) {\n    http_response_code(401);\n    exit;\n}\n\n$event = json_decode($body, true);\nhttp_response_code(200);<\/code><\/pre>\n\n\n\n
    Common reasons the signature does not match<\/h2>\n\n\n\n
    Hashing parsed JSON.<\/strong> This is the number one mistake. JSON.stringify(req.body)<\/code> or json.dumps(payload)<\/code> produces text that differs from the original: whitespace, key order and character escaping change. One different byte changes the whole hash. Always sign the bytes you received.<\/p>\n\n\n\n
    Wrong encoding.<\/strong> Converting the body to a string with the wrong charset (Latin-1 instead of UTF-8, for example) alters accented names and emoji. Stay in bytes until validation is done.<\/p>\n\n\n\n
    Wrong secret.<\/strong> The right value is the app secret of the app subscribed to the webhook. It is not the access token, not the verify token, and not the secret of another app in the same business portfolio. If you run separate apps for staging and production, each environment needs its own.<\/p>\n\n\n\n
    Ignoring the prefix.<\/strong> The header carries sha256=<\/code> before the hash. Either compare the full string (as in the examples) or strip the prefix on both sides.<\/p>\n\n\n\n
    Middleware or gateways changing the body.<\/strong> Proxies, API gateways and serverless platforms sometimes reformat or encode the body before your code sees it. If validation fails only in production, log the received body length and compare it with Content-Length<\/code>.<\/p>\n\n\n\n
    Secret rotated, server not updated.<\/strong> After you reset the app secret in the dashboard, events are signed with the new value. If your server rejects everything with 401, Meta keeps retrying: per the webhooks overview<\/a>, deliveries that do not get a 200<\/code> are retried with decreasing frequency for up to 7 days, which can produce duplicate events. Monitor your endpoint’s 401 rate to catch this early.<\/p>\n\n\n\n
    Good practices after validation<\/h2>\n\n\n\n