How to verify webhook signatures (HMAC-SHA256)
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
- Read the raw request body before parsing it as JSON.
- Compute
"sha256=" + hex(HMAC_SHA256(secret, raw_body)). - Compare it with
X-Sahaab-Signaturewith a constant-time comparison. - If it differs, answer
401and ignore the message. - If it matches, store the message's
id. If you have seen thatidbefore, answer200and do nothing. - Answer any
2xxwithin 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.
Thank you — this helps us improve the article.
Still stuck?
Ask the AI about your exact situation — it answers from this knowledge base — or contact us.
Related articles
- How to add a webhook (get notified when accounts change)
Send a signed JSON message to your billing, monitoring or chat system when an account is created, suspended or terminated, a mailbox is added and more.
- Webhook events and JSON payloads reference
Every webhook event the server sends — accounts, domains, mailboxes, disk and bandwidth limits, failed tasks, support tickets — with the JSON body of each.
- Webhooks explained: notify other systems of server events
Send a signed JSON message to your billing, monitoring or chat system when accounts, domains, mailboxes, limits, tasks or tickets change.
- How to install Ubuntu updates and security fixes from the panel
See waiting Ubuntu package updates, install only security fixes or all updates, and restart the server when an update needs it, from the admin panel.