Verificação de assinaturas de webhooks do GitHub: X-Hub-Signature-256, comparação em tempo constante e IDs de entrega

O que é

A documentação de webhooks do GitHub afirma que "the hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header" e que "GitHub uses an HMAC hex digest to compute the hash. The hash signature always starts with sha256=." O digest é o HMAC-SHA256 do corpo bruto da requisição, calculado com o segredo configurado no webhook. Toda entrega também traz o cabeçalho X-GitHub-Delivery, descrito na referência de eventos e payloads de webhooks do GitHub como "a globally unique identifier (GUID) to identify the event". É esse o campo que deve servir de chave para a deduplicação, e não qualquer campo dentro do corpo JSON. Quando há um segredo configurado, o GitHub também envia um cabeçalho legado X-Hub-Signature; a própria documentação diz que ele "uses the HMAC-SHA1 algorithm and is only included for legacy purposes" e recomenda usar o cabeçalho SHA-256. Se nenhum segredo estiver configurado, nenhum dos dois cabeçalhos é enviado.

Por que importa

Qualquer pessoa pode fazer um POST para a URL pública de um webhook. Sem a verificação da assinatura, o endpoint não consegue distinguir uma entrega legítima do GitHub de uma forjada. Basear a validação apenas em X-Hub-Signature significa depender da variante legada com SHA-1, que o próprio GitHub desaconselha.

Como aplicar

• Leia os bytes brutos do corpo antes que qualquer parser de JSON os toque (veja o artigo sobre a armadilha do corpo bruto).
• Calcule hmac_sha256(secret, raw_body) e compare o resultado com o digest que vem depois do prefixo sha256= em X-Hub-Signature-256.
• Use uma comparação em tempo constante. A documentação do GitHub sugere "a method like secure_compare or crypto.timingSafeEqual"; nunca use == nem .equals() nas strings hexadecimais.
• Teste com o vetor publicado pelo GitHub: o segredo It's a Secret to Everybody e o payload Hello, World! devem resultar em sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17.
• Guarde X-GitHub-Delivery junto com os resultados processados e ignore qualquer entrega cujo ID já tenha sido processado: o GitHub não faz novas tentativas por conta própria, mas um reenvio manual ou via API reutiliza o valor original de X-GitHub-Delivery.
• Responda com um 2xx em até 10 segundos; o GitHub registra respostas mais lentas como falhas do tipo timed out.
• Se houver um segredo configurado, rejeite entregas sem nenhum cabeçalho de assinatura; isso indica um remetente mal configurado ou forjado.

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

Armadilhas

Verificar contra X-Hub-Signature (SHA-1) porque uma biblioteca usa esse cabeçalho por padrão: o GitHub envia os dois quando há um segredo, mas apenas o cabeçalho SHA-256 deve decidir se a entrega é aceita. Comparar assinaturas com uma igualdade de strings que para no primeiro byte diferente, o que vaza informação de tempo. Derivar a chave da entrega a partir do conteúdo do evento em vez de X-GitHub-Delivery, o que falha quando dois eventos diferentes compartilham legitimamente os mesmos campos no corpo.