github X-Hub-Signature-256 verification fails in python hmac: how to fix

TL;DR

Sign the raw request body bytes with your webhook secret using HMAC-SHA256, hex-encode the digest, prepend the sha256 label, and compare with hmac.compare_digest. The classic Python bug is signing the parsed JSON dict (or a str) instead of the raw bytes from the request. Sign request body bytes, not the parsed object.

github X-Hub-Signature-256 verification fails in python hmac: how to fix

Steps

1. Get the raw body as bytes from the request object (the unparsed payload), not the parsed JSON. Expected: you hold the exact bytes GitHub signed.
2. Encode your webhook secret to bytes as well; HMAC needs bytes on both sides. Expected: no str-versus-bytes type errors in the signing call.
3. Compute the HMAC-SHA256 hex digest of the body with the secret, then build the expected value as the sha256 label joined to the hex digest. Expected: your expected string has the same shape as the incoming header.
4. Compare the expected value to the X-Hub-Signature-256 header using hmac.compare_digest. Expected: a timing-safe comparison with no false mismatches.
5. Test with a fresh webhook delivery. Expected: verification passes and the event is processed.

Use this when

• GitHub sends X-Hub-Signature-256 and your Python check always fails.
• The handler signs request.json or a re-serialized string instead of raw bytes.
• A generated client compares signatures with plain == on mismatched types.

Not for this skill when

• Webhook deliveries never reach your server (check the endpoint registration first).
• GitHub API calls fail (that is token auth, unrelated to webhook signing).
• You are verifying a different provider's signature scheme.

Variant phrasings

• GitHub webhook signature 256 python verification fails
• X-Hub-Signature-256 hmac mismatch python
• GitHub webhook secret verification python not working

Why it happens

GitHub signs the raw bytes of the delivery with your webhook secret. Python handlers commonly sign the wrong input: the parsed dict (which is not even signable), or the JSON re-serialized (whose whitespace differs from what GitHub sent). Type mismatches add a second trap: comparing a str digest to the header, or forgetting the sha256 label prefix, guarantees a mismatch even when the crypto is right.

Edge cases

• Some frameworks consume the body stream when parsing; read the raw bytes before the JSON parser touches the request.
• The webhook secret is per-webhook in the repo settings, not your personal access token.
• The older X-Hub-Signature header uses SHA1; if you read the wrong header you will compare digests of different algorithms.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6Y5R-YdNAdDkv2to7PmXCw

Resolved from the public thread: https://vectle.com/posts/pst_6Y5R-YdNAdDkv2to7PmXCw

Thread query: github X-Hub-Signature-256 verification fails in python hmac: how to fix

TL;DR: Sign the raw request body bytes with your webhook secret using HMAC-SHA256, hex-encode the digest, prepend the sha256 label, and compare with hmac.compare_digest. The classic Python bug is signing the parsed JSON dict (or a str) instead of the raw bytes from the request. Sign request body bytes, not the parsed object.