Verifying GitHub webhook signatures: X-Hub-Signature-256, timing-safe comparison and delivery IDs

What it is

GitHub's webhook documentation states that "the hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header" and that "GitHub uses an HMAC hex digest to compute the hash. The hash signature always starts with sha256=." The digest is HMAC-SHA256 of the raw request body, keyed with the secret configured on the webhook. Every delivery also carries X-GitHub-Delivery, described in GitHub's webhook events and payloads reference as "a globally unique identifier (GUID) to identify the event" — this is the field to key deduplication on, not any field inside the JSON body. A legacy X-Hub-Signature header is also sent when a secret is configured; GitHub's own docs say it "uses the HMAC-SHA1 algorithm and is only included for legacy purposes" and recommend the SHA-256 header instead. Neither header is sent at all if no secret is configured.

Why it matters

Anyone can POST to a public webhook URL. Without signature verification, an endpoint cannot tell a genuine GitHub delivery from a forged one, and gating on X-Hub-Signature alone relies on the legacy SHA-1 variant that GitHub itself recommends against.

How to apply

• Read the raw body bytes before any JSON parsing touches them (see the raw-body trap article).
• Compute hmac_sha256(secret, raw_body) and compare it against the digest after the sha256= prefix in X-Hub-Signature-256.
• Use a constant-time comparison — GitHub's docs suggest "a method like secure_compare or crypto.timingSafeEqual" — never == or .equals() on the hex strings.
• Test against GitHub's published vector: secret It's a Secret to Everybody, payload Hello, World! must give sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17.
• Store X-GitHub-Delivery alongside processed results and skip any delivery whose ID was already processed: GitHub does not retry on its own, but a manual or API redelivery reuses the original X-GitHub-Delivery value.
• Respond with a 2xx within 10 seconds; GitHub records slower responses as timed out failures.
• Reject deliveries with no signature header at all if a secret is configured; that indicates a misconfigured or forged sender.

import hashlib, hmac

def verify_github(secret: bytes, raw_body: bytes, header: str) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    # compare bytes: compare_digest raises TypeError on non-ASCII str input
    return hmac.compare_digest(expected.encode(), header.encode())

Pitfalls

Verifying against X-Hub-Signature (SHA-1) because a library defaults to it; GitHub sends both when a secret is set, but only the SHA-256 header should gate acceptance. Comparing signatures with a short-circuiting string equality, which leaks timing information. Deriving a delivery key from event content instead of X-GitHub-Delivery, which breaks once two different events legitimately share the same body fields.