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

1import hashlib
2import hmac
3 
4 
5def sign(secret: bytes, raw_body: bytes) -> str:
6    """Sender: HMAC-SHA256 over the exact body bytes, sent as "sha256=<hex>"."""
7    return "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
8 
9 
10def verify(secret: bytes, raw_body: bytes, header: str | None) -> bool:
11    """Receiver: recompute over the raw body and compare in constant time."""
12    if header is None:
13        return False  # a missing header fails, it never skips the check
14    # bytes on both sides: compare_digest raises TypeError for non-ASCII str
15    return hmac.compare_digest(sign(secret, raw_body).encode(), header.encode())
16 

1import os
2 
3from flask import Flask, abort, request
4 
5from webhook import verify
6 
7app = Flask(__name__)
8SECRET = os.environ["WEBHOOK_SECRET"].encode()  # fails at start-up when unset
9 
10 
11@app.post("/webhook")
12def webhook():
13    raw_body = request.get_data()  # the bytes as received, before any JSON parsing
14    if not verify(SECRET, raw_body, request.headers.get("X-Hub-Signature-256")):
15        abort(401)
16    event = request.get_json()
17    return f"accepted {event['action']} #{event['number']}\n"
18 

How it works

1. hmac.new(secret, raw_body, hashlib.sha256).hexdigest() gives the 64 hex digits; the header value is sha256= followed by them.
2. hmac.compare_digest takes as long for a forged MAC that matches in 63 digits as for one that matches in none, unlike ==, which stops at the first difference.
3. Both sides of the comparison are encoded to bytes first, so any header value — including non-ASCII text a client made up — gives False instead of an exception.
4. In Flask, request.get_data() returns the body bytes exactly as received; verify them, then call request.get_json(). The run feeds GitHub's example (Hello, World!, secret It's a Secret to Everybody) and gets sha256=757107ea…3e17.
5. The secret comes from the WEBHOOK_SECRET environment variable; os.environ[...] makes the app fail at start-up when it is missing instead of signing with an empty key.

Gotchas

• hmac.new(key, msg) without a hash raises TypeError: Missing required argument 'digestmod'. (Python 3.8 and later); always pass hashlib.sha256.
• hmac.compare_digest accepts two str only if both are ASCII — compare_digest("sha256=é", header) raises TypeError: comparing strings with non-ASCII characters is not supported — and refuses to mix str with bytes. Encode both sides, as verify does.
• The MAC covers bytes, not JSON. json.dumps(json.loads(body)) turns the provider's pretty-printed body into a different byte string, and the route rejects it with 401. Verify request.get_data(), never a re-serialized request.json.
• A missing header (None) must fail the request, not skip the check — verify returns False for it.

Related recipes

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