How to verify webhook signatures (HMAC-SHA256)

For server administrators · Updated 2026-10-29

On this page
  1. The headers
  2. Steps
  3. PHP
  4. Node.js (Express)
  5. Python (Flask)
  6. Common questions

Anyone who knows your webhook address could send it fake messages. Each real message is signed with the webhook's secret, so your system can check it came from the server and was not changed.

The headers

Each message is a POST with a JSON body and these headers:

Content-Type: application/json
User-Agent: Sahaab-Webhooks/1
X-Sahaab-Event: account.suspended
X-Sahaab-Delivery: 42
X-Sahaab-Signature: sha256=5d1c…

X-Sahaab-Signature is sha256= followed by the HMAC-SHA256 of the raw body, as lowercase hex, with your signing secret as the key. X-Sahaab-Delivery is the number of the delivery.

Steps

  1. Read the raw request body before parsing it as JSON.
  2. Compute "sha256=" + hex(HMAC_SHA256(secret, raw_body)).
  3. Compare it with X-Sahaab-Signature with a constant-time comparison.
  4. If it differs, answer 401 and ignore the message.
  5. If it matches, store the message's id. If you have seen that id before, answer 200 and do nothing.
  6. Answer any 2xx within 10 seconds. Do slow work after answering.

PHP

$secret = getenv('WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SAHAAB_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
http_response_code(200);

Node.js (Express)

const crypto = require('crypto');
app.post('/hooks/hosting', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest('hex');
  const got = req.get('X-Sahaab-Signature') || '';
  if (got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Python (Flask)

import hmac, hashlib, os
from flask import request, abort

@app.post('/hooks/hosting')
def hook():
    expected = 'sha256=' + hmac.new(os.environ['WEBHOOK_SECRET'].encode(), request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get('X-Sahaab-Signature', '')):
        abort(401)
    event = request.get_json()
    return '', 200

Common questions

The signature never matches. Why?

Usually the body was parsed and re-encoded before hashing. Hash the exact bytes received. Also check you use the secret of this webhook: click Show secret in Webhooks.

Can I check the time of a message?

Yes. The body's time is when the event happened, in UTC (ISO 8601). Retries keep the original time.

Was this article helpful?

Still stuck?

Ask the AI about your exact situation — it answers from this knowledge base — or contact us.