A especificação Standard Webhooks versus o cabeçalho HMAC da Shopify e o token de segredo compartilhado do GitLab

O que é

A especificação Standard Webhooks define três cabeçalhos em cada entrega: webhook-id (identificador único da mensagem), webhook-timestamp (segundos Unix) e webhook-signature, enviado como uma lista de valores v1,<base64 signature> separados por espaço "para permitir a rotação de segredos sem indisponibilidade" (entradas assimétricas v1a, também podem aparecer). O conteúdo assinado é msg_id.timestamp.payload, e o segredo compartilhado é "codificado em base64, com o prefixo whsec_ para fácil identificação": a chave HMAC é o restante decodificado de base64, não o texto em si. A documentação do GitLab afirma que seus tokens de assinatura (introduzidos na 19.0, com disponibilidade geral no GitLab 19.1) seguem esse modelo: "a entrega de webhooks do GitLab segue a especificação Standard Webhooks", e orienta os receptores a remover whsec_ e decodificar o restante de base64. Já o mecanismo mais antigo do GitLab, o token secreto, é "enviado como texto simples no cabeçalho HTTP X-Gitlab-Token": uma comparação direta de strings, não um HMAC, que a própria documentação do GitLab hoje descreve como a opção com "garantias de segurança mais fracas" e que não recomenda mais para novos webhooks. A Shopify usa um terceiro esquema, totalmente diferente: o cabeçalho X-Shopify-Hmac-SHA256, codificado em base64, é verificado calculando o "HMAC-SHA256 do corpo bruto da requisição usando o client secret do seu app como chave" e comparando o resultado "com o valor decodificado do cabeçalho". A assinatura da Shopify não tem timestamp, portanto não há janela de replay; faça a deduplicação com base em X-Shopify-Webhook-Id.

Por que importa

Existem três formas de "segurança de webhooks" em uso amplo, e uma biblioteca cliente ou um exemplo de código feito para uma delas falha silenciosamente nas outras: uma construção HMAC compartilhada (Standard Webhooks e, agora, o token de assinatura do GitLab), um HMAC proprietário em um único cabeçalho (Shopify) e uma comparação de segredo compartilhado, sem criptografia (o token legado do GitLab e esquemas semelhantes).

Como aplicar

• Para qualquer provedor que afirme seguir o Standard Webhooks (o token de assinatura do GitLab é um deles), verifique webhook-signature recalculando o HMAC-SHA256 sobre id.timestamp.payload, usando como chave os bytes decodificados de base64 que vêm depois de whsec_; codifique o digest em base64, adicione o prefixo v1, e aceite a mensagem se qualquer entrada separada por espaço coincidir, usando comparação em tempo constante. Verifique também se webhook-timestamp é recente.
• Para a Shopify, decodifique o cabeçalho de base64 e compare os 32 bytes resultantes com o digest HMAC-SHA256 bruto do corpo, nunca com um digest em hexadecimal. Após a rotação do client secret, a Shopify pode continuar assinando com o segredo antigo por até uma hora.
• Para o X-Gitlab-Token legado do GitLab, compare-o com o token secreto configurado (a comparação em tempo constante continua sendo recomendável); não há assinatura a recalcular. Migre para o token de assinatura onde estiver disponível.
• Nunca trate um token de segredo compartilhado simples como equivalente a um HMAC: o token viaja em todas as requisições, então qualquer ponto que consiga ler uma única requisição (um proxy de logs, um intermediário que termina TLS) pode forjar payloads arbitrários, enquanto um HMAC nunca expõe a chave e a vincula a um corpo exato.

import base64, hashlib, hmac

def verify_standard(secret: str, msg_id: str, ts: str, raw_body: bytes, header: str) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = msg_id.encode() + b"." + ts.encode() + b"." + raw_body
    expected = b"v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    return any(hmac.compare_digest(expected, s.encode()) for s in header.split(" "))

Armadilhas

Aplicar código de verificação HMAC a um provedor que usa apenas um token de segredo compartilhado (não há nada para calcular o hash), ou supor que comparar um token de segredo compartilhado em tempo constante resolve a diferença em relação a um HMAC. Não perceber que o GitLab agora oferece os dois mecanismos lado a lado na mesma tela de configuração de webhook.