Como validar a assinatura de um webhook

Uma URL de webhook pode receber requisições de qualquer origem capaz de alcançá-la. O fato de o corpo mencionar um contrato conhecido não prova que o evento veio do sistema esperado. A validação da assinatura permite conferir se o conteúdo corresponde ao mecanismo de autenticação acordado com o remetente antes de produzir alterações no CRM.

Considere uma integração fictícia de aprovação de contratos. Ela recebe eventos e cria tarefas de implantação. Sem validação, alguém que descubra o formato poderia tentar enviar um evento semelhante. O receptor precisa separar uma entrega válida de um conteúdo apenas plausível.

Leia a especificação do remetente

Identifique o cabeçalho usado, o algoritmo, a forma de obter a chave e o conteúdo exato que entra no cálculo. Alguns fornecedores assinam o corpo; outros combinam corpo, horário e outros elementos. Não escolha um padrão por familiaridade nem copie o nome de um cabeçalho de outra API.

Como exemplo concreto, a documentação do GitHub descreve a validação com segredo compartilhado e HMAC-SHA256 no cabeçalho X-Hub-Signature-256. Ela orienta a guardar o segredo de forma segura e a comparar a assinatura de modo resistente a diferenças de tempo. Esse é o contrato do GitHub; outro serviço pode exigir um procedimento diferente.

Preserve os bytes que foram assinados

Quando a assinatura cobre o corpo original, faça a verificação antes de alterar sua representação. Interpretar JSON e gerar novamente o texto pode mudar espaços, ordem de propriedades ou codificação. O conteúdo pode parecer igual para uma pessoa e ainda assim resultar em uma assinatura diferente.

Confira como o framework disponibiliza o corpo bruto e como os componentes anteriores tratam a requisição. Um intermediário ou middleware pode consumir ou transformar o conteúdo antes do validador. Registre essas dependências para que uma mudança de infraestrutura não quebre a verificação silenciosamente.

Organize a sequência do receptor

1. Receba a requisição por HTTPS no endpoint previsto.
2. Valide limites de tamanho e a presença dos elementos exigidos.
3. Recupere o segredo correto para a origem e o ambiente.
4. Calcule e compare a assinatura conforme a documentação.
5. Rejeite o que não passar na validação.
6. Somente então interprete e encaminhe o evento para o processamento autorizado.

Não devolva detalhes que revelem segredos ou facilitem a adivinhação da assinatura. Nos registros internos, anote uma categoria de falha, o horário e um identificador de correlação quando disponível. Evite gravar automaticamente todo o corpo: ele pode conter informações que não são necessárias ao diagnóstico.

Separe autenticidade de repetição

Uma assinatura válida não impede que um evento legítimo seja entregue novamente. Quando o protocolo inclui um horário assinado e uma tolerância, aplique a regra documentada e mantenha o relógio do servidor correto. Ainda assim, use identificação do evento para controlar efeitos repetidos.

Também não confunda a validade da assinatura com autorização para qualquer alteração. Depois de validar a origem, confira o tipo de evento, a conta, o objeto e o escopo permitido. Uma integração autorizada a atualizar situação de contrato não deve ganhar permissão implícita para administrar usuários.

Prepare os testes de aceitação e rejeição

Use eventos de teste ou exemplos oficiais do fornecedor. Quando uma entrega válida for rejeitada, confira primeiro corpo bruto, codificação, segredo e prefixos esperados. Desativar a validação em produção para “ver se funciona” remove justamente a proteção que o teste deveria comprovar.

Planeje a troca do segredo com os responsáveis pelas duas pontas e confirme como o fornecedor permite a transição. Complete o receptor com controle de idempotência e uma política de falhas e retentativas. A validação é a porta de entrada de um fluxo que também precisa ser recuperável e auditável.