Tudo o que vale a pena saber, nada do que não vale.
Como a assinatura é construída
Uma construção comum forma a string canónica como `${timestamp}.${requestBody}`, calcula `HMAC-SHA256(canonical, secret)`, codifica o resultado em hexadecimal e envia o digest e o timestamp num cabeçalho de assinatura. Incluir o timestamp no payload assinado impede ataques de repetição — o seu endpoint deve rejeitar webhooks com mais de 5 minutos. Os nomes dos cabeçalhos e o formato canónico exato variam entre plataformas, então confirme-os com o seu fornecedor antes de escrever o código de verificação.
Porque usar assinaturas HMAC em vez de RSA?
O HMAC é simétrico — ambos os lados partilham um segredo — o que significa que a assinatura e a verificação são aproximadamente 10.000 vezes mais rápidas do que o RSA-2048. Para o envio de dados via webhook, onde um único SMSC pode emitir 50.000 DLRs por segundo, a assinatura RSA domina o uso da CPU. O HMAC-SHA256 em hardware moderno leva apenas alguns microssegundos. A contrapartida: qualquer pessoa com o segredo pode assinar, por isso o segredo deve ser partilhado apenas entre a plataforma e o seu ambiente, armazenado como qualquer outra credencial e poder ser rotacionado a pedido.
Armadilhas da verificação
Três bugs comuns. Comparar strings com `==` em vez de uma comparação de tempo constante (ataque de temporização — use `crypto.timingSafeEqual`). Validar a assinatura após analisar o corpo da requisição JSON (você deve verificar os bytes brutos, não uma representação serializada — reordenar o JSON quebra o hash). Esquecer a janela anti-replay do timestamp.
Além do HMAC
Para ambientes regulados (bancos, saúde), algumas plataformas também oferecem entrega de webhooks por mTLS — o remetente apresenta um certificado de cliente que o seu balanceador de carga valida antes de a requisição chegar à aplicação. Isso é mais forte que HMAC porque vincula a entrega a uma chave de hardware, mas só compensa o custo em cargas de trabalho realmente sensíveis. Para a maioria das integrações, HMAC-SHA256 sobre HTTPS é a resposta certa.