GitHub-Webhook-Signaturen prüfen: X-Hub-Signature-256, zeitkonstanter Vergleich und Delivery-IDs

Worum es geht

In der Webhook-Dokumentation von GitHub heisst es: "the hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header" und "GitHub uses an HMAC hex digest to compute the hash. The hash signature always starts with sha256=." Der Digest ist der HMAC-SHA256 des rohen Request-Body, berechnet mit dem Secret, das am Webhook konfiguriert ist. Jede Auslieferung enthält ausserdem X-GitHub-Delivery; die GitHub-Referenz zu Webhook-Events und Payloads beschreibt den Header als "a globally unique identifier (GUID) to identify the event". Dieses Feld ist der Schlüssel für die Deduplizierung, nicht ein Feld im JSON-Body. Ist ein Secret konfiguriert, wird zusätzlich ein veralteter Header X-Hub-Signature gesendet; GitHubs eigene Dokumentation schreibt über diesen Header, er "uses the HMAC-SHA1 algorithm and is only included for legacy purposes", und empfiehlt stattdessen den SHA-256-Header. Ist kein Secret konfiguriert, wird keiner der beiden Header gesendet.

Warum es wichtig ist

Jeder kann an eine öffentliche Webhook-URL einen POST senden. Ohne Signaturprüfung kann ein Endpunkt eine echte GitHub-Auslieferung nicht von einer gefälschten unterscheiden. Wer allein anhand von X-Hub-Signature entscheidet, verlässt sich auf die veraltete SHA-1-Variante, von der GitHub selbst abrät.

So wird es angewendet

• Die rohen Body-Bytes lesen, bevor ein JSON-Parser sie anfasst (siehe den Artikel zur Raw-Body-Falle).
• hmac_sha256(secret, raw_body) berechnen und mit dem Digest nach dem Präfix sha256= in X-Hub-Signature-256 vergleichen.
• Einen zeitkonstanten Vergleich verwenden – GitHubs Dokumentation empfiehlt "a method like secure_compare or crypto.timingSafeEqual" –, niemals == oder .equals() auf den Hex-Strings.
• Gegen den von GitHub veröffentlichten Testvektor prüfen: Secret It's a Secret to Everybody und Payload Hello, World! müssen sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17 ergeben.
• X-GitHub-Delivery zusammen mit den verarbeiteten Ergebnissen speichern und jede Auslieferung überspringen, deren ID bereits verarbeitet wurde: GitHub wiederholt Auslieferungen nicht von sich aus, aber eine manuelle oder per API ausgelöste erneute Zustellung übernimmt den ursprünglichen Wert von X-GitHub-Delivery.
• Innerhalb von 10 Sekunden mit einem 2xx-Status antworten; langsamere Antworten verzeichnet GitHub als Fehler vom Typ timed out.
• Auslieferungen ohne Signatur-Header ablehnen, sofern ein Secret konfiguriert ist; das deutet auf einen falsch konfigurierten oder gefälschten Absender hin.

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())

Stolpersteine

Prüfung gegen X-Hub-Signature (SHA-1), weil eine Bibliothek dies als Standard verwendet: GitHub sendet beide Header, sobald ein Secret gesetzt ist, aber nur der SHA-256-Header sollte über die Annahme entscheiden. Vergleich der Signaturen mit einem abbrechenden String-Vergleich, der Informationen über das Zeitverhalten preisgibt. Ableitung eines Delivery-Schlüssels aus dem Event-Inhalt statt aus X-GitHub-Delivery; das schlägt fehl, sobald zwei verschiedene Events legitimerweise dieselben Body-Felder aufweisen.