HMAC em Python: Valide Assinaturas de Webhooks

HMAC combina um segredo compartilhado com uma função hash para autenticar uma mensagem. Em webhooks, o provedor assina os bytes enviados e sua aplicação calcula o mesmo valor antes de confiar no evento.

import hashlib
import hmac

def assinatura_valida(corpo: bytes, recebida: str, segredo: bytes) -> bool:
    esperada = hmac.new(segredo, corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, recebida)

payload = b'{"evento":"pedido.criado"}'
print(assinatura_valida(payload, "digest-recebido", b"segredo"))

Use exatamente o algoritmo e o formato descritos pelo provedor, que pode incluir prefixos ou timestamp na mensagem assinada. Leia o corpo bruto antes do parsing e carregue o segredo por configuração protegida. Nunca registre o segredo nem o header completo em logs.

Boas práticas

Compare com hmac.compare_digest() para reduzir vazamentos por tempo de execução. Rejeite assinaturas ausentes ou malformadas antes de processar o evento. Para mitigar replay, valide uma janela de tempo e armazene IDs já consumidos. Faça rotação de segredo com um período controlado que aceite a chave anterior.

Entenda o digest básico em hashlib e integridade de arquivos. O guia de segurança de APIs cobre autorização, limites e logs.

A documentação oficial de hmac, consultada em 22 de julho de 2026, detalha a API e seus limites.