Verificación de firmas de webhooks de GitHub: X-Hub-Signature-256, comparación en tiempo constante e IDs de entrega

Qué es

La documentación de webhooks de GitHub indica que "the hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header" y que "GitHub uses an HMAC hex digest to compute the hash. The hash signature always starts with sha256=." El digest es el HMAC-SHA256 del cuerpo sin procesar de la petición, calculado con el secreto configurado en el webhook. Además, cada entrega incluye X-GitHub-Delivery, descrito en la referencia de eventos y cargas útiles de webhooks de GitHub como "a globally unique identifier (GUID) to identify the event"; este es el campo sobre el que debe basarse la deduplicación, y no ningún campo dentro del cuerpo JSON. Cuando hay un secreto configurado, también se envía la cabecera heredada X-Hub-Signature; la propia documentación de GitHub dice que "uses the HMAC-SHA1 algorithm and is only included for legacy purposes" y recomienda usar en su lugar la cabecera SHA-256. Si no hay ningún secreto configurado, no se envía ninguna de las dos cabeceras.

Por qué importa

Cualquiera puede enviar un POST a la URL pública de un webhook. Sin verificación de firma, un endpoint no puede distinguir una entrega genuina de GitHub de una falsificada, y basarse solo en X-Hub-Signature implica depender de la variante heredada con SHA-1, que el propio GitHub desaconseja.

Cómo aplicarlo

• Lee los bytes del cuerpo sin procesar antes de que cualquier análisis de JSON los toque (véase el artículo sobre la trampa del cuerpo sin procesar).
• Calcula hmac_sha256(secret, raw_body) y compáralo con el digest que sigue al prefijo sha256= en X-Hub-Signature-256.
• Usa una comparación en tiempo constante; la documentación de GitHub sugiere "a method like secure_compare or crypto.timingSafeEqual". No uses nunca == ni .equals() sobre las cadenas hexadecimales.
• Prueba tu implementación con el vector publicado por GitHub: con el secreto It's a Secret to Everybody y la carga Hello, World! debe obtenerse sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17.
• Guarda X-GitHub-Delivery junto con los resultados procesados y omite cualquier entrega cuyo ID ya se haya procesado: GitHub no reintenta por su cuenta, pero un reenvío manual o mediante la API reutiliza el valor original de X-GitHub-Delivery.
• Responde con un 2xx en menos de 10 segundos; GitHub registra las respuestas más lentas como fallos timed out.
• Rechaza las entregas que no traigan ninguna cabecera de firma si hay un secreto configurado; eso indica un emisor mal configurado o falsificado.

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

Trampas

Verificar contra X-Hub-Signature (SHA-1) porque una biblioteca lo usa por defecto: GitHub envía ambas cabeceras cuando hay un secreto, pero solo la cabecera SHA-256 debe determinar si se acepta la entrega. Comparar firmas con una igualdad de cadenas que termina en cuanto encuentra una diferencia, lo que filtra información de temporización. Derivar la clave de entrega a partir del contenido del evento en lugar de X-GitHub-Delivery, lo cual falla en cuanto dos eventos distintos comparten legítimamente los mismos campos en el cuerpo.