ForHosting KIT · Ferramentas para dev

Como verificar a assinatura de webhook com HMAC

Informe o algoritmo HMAC, como HMAC-SHA256, e o cabeçalho que traz a assinatura, e receba 8 passos em ordem: guardar o corpo bruto, reconstruir a mensagem assinada, comparar em tempo constante e barrar repetições. Grátis no seu navegador.

Grátis
Funciona no seu navegador
Sem cadastro
Seus dados não saem do seu aparelho

Executar grátis Ver a API

Use pelo WebAPIE-mailTelegramApp em breve

Esta capacidade converte o algoritmo HMAC e o cabeçalho do provedor em uma lista precisa e ordenada.

O que uma assinatura HMAC prova

Quem envia a notificação calcula um HMAC com um segredo compartilhado sobre os bytes exatos da mensagem e coloca o resultado num cabeçalho. Ao receber, o seu sistema refaz a mesma conta: pega o corpo bruto, exatamente como chegou, junta o carimbo de tempo ou o prefixo que o provedor exige, aplica o algoritmo informado e codifica o resultado do jeito documentado, em geral hexadecimal ou Base64. Se as duas assinaturas batem, alguém que conhece o segredo produziu aquela mensagem. Isso não prova que ela é recente nem que ainda não foi processada; por isso vêm depois a janela de tolerância do carimbo de tempo e o registro dos identificadores de evento já aceitos.

Erros comuns e quando usar a lista

A falha mais frequente acontece antes da conta: o sistema lê e reorganiza o corpo, mudando espaços, ordem ou quebras de linha, e a assinatura correta deixa de bater. Outros erros típicos são aceitar um cabeçalho vazio ou duplicado, comparar textos com igualdade comum e cortar ou completar valores de tamanho diferente em vez de rejeitá-los. Use os passos ao implementar ou revisar um receptor e ao montar um plano de verificação com corpos alterados, carimbos vencidos, segredos errados e eventos repetidos. A documentação do provedor continua sendo a referência para o formato do cabeçalho.

Comece pelos bytes assinados pelo provedor

Preserve exatamente os bytes recebidos antes de interpretar o corpo. Leia o cabeçalho indicado sem diferenciar maiúsculas no nome, mas valide o valor com rigor. O provedor pode enviar um resumo simples ou incluir versão, data e várias assinaturas.

Siga a gramática documentada, rejeite valores ausentes, vazios, duplicados ou malformados e mantenha o segredo em um gerenciador protegido.

Reconstrua, calcule e compare na ordem correta

Reconstrua exatamente a mensagem assinada: ela pode ser apenas o corpo bruto ou uma data, um separador e o corpo. Respeite a ordem e a codificação documentadas. Calcule o HMAC com o segredo e o algoritmo normalizado e codifique o resultado conforme o provedor.

Decodifique as assinaturas em bytes de igual tamanho e use comparação em tempo constante. Codificação inválida ou tamanhos diferentes significam falha; não corte nem complete valores.

Trate a criptografia como parte da aceitação

Um HMAC correspondente prova conhecimento do segredo, mas não garante que a mensagem seja recente ou inédita. Aplique a tolerância de data recomendada, registre identificadores aceitos e torne o processamento idempotente. Faça a rotação de segredos conforme a sobreposição documentada.

Rejeite antes de enfileirar trabalho, devolva erro genérico e registre somente códigos seguros. Teste corpos alterados, datas vencidas, cabeçalhos inválidos, segredos errados e eventos repetidos.

Casos de uso

Revisar uma integração existente

Confira se captura, HMAC, comparação segura e proteção contra repetição estão na sequência correta.

Preparar testes de segurança

Crie testes negativos para cabeçalhos ausentes, corpos alterados, resumos inválidos, datas vencidas e repetições.

Perguntas frequentes

Quais algoritmos são reconhecidos?

HMAC-SHA1, HMAC-SHA256, HMAC-SHA384 e HMAC-SHA512. Outro algoritmo gera erro de entrada.

Por que preservar o corpo bruto?

Interpretar e serializar novamente pode alterar os bytes e invalidar uma assinatura correta.

Um HMAC válido impede repetição?

Não. Valide a data assinada e elimine identificadores duplicados quando disponíveis.

Por que comparar a assinatura em tempo constante?

Porque uma comparação comum pode revelar, pelo tempo de resposta, quanto da assinatura coincidiu. Converta os dois valores em bytes de mesmo tamanho e use uma comparação segura contra medição de tempo; tamanho ou decodificação diferente conta como falha.

Preciso informar meu segredo ou a mensagem recebida?

Não. A lista de passos só precisa do algoritmo HMAC e do nome do cabeçalho de assinatura, então o segredo, a mensagem e a assinatura ficam dentro do seu próprio receptor.

Ferramentas relacionadas

Para desenvolvedores — acesso via API

Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.

Endpoint

POSThttps://api.kit.forhosting.com/security/webhook-signature-verify-steps

Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.

Chame do seu código

curl -X POST https://api.kit.forhosting.com/security/webhook-signature-verify-steps \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}'

const res = await fetch("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/security/webhook-signature-verify-steps",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/security/webhook-signature-verify-steps", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemplo de requisição

{
  "algorithm": "HMAC-SHA256",
  "header_name": "X-Webhook-Signature"
}

Exemplo de resposta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "security.webhook_signature_verify_steps",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.

Preço

por chamadaUS$ 0,002

Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.

Erros

HTTP	Código	O que significa
`401`	`unauthorized`	Token ausente ou inválido. Confira o header Authorization.
`402`	`insufficient_balance`	Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo.
`404`	`unknown_type`	Esse tipo de tarefa não existe. Confira o campo type no catálogo.
`429`	`rate_limited`	Muitas requisições em pouco tempo. Espere um instante e tente de novo.

Notas técnicas

A verificação de assinaturas de webhook costuma falhar nas interfaces: o framework altera o corpo, o cabeçalho é interpretado sem rigor ou uma comparação comum revela informações de tempo. Ela não precisa do payload, do segredo nem da assinatura. Use o resultado ao implementar ou revisar o endpoint e confirme formato de data, codificação e tolerância a repetição na documentação oficial.

Comece pelos bytes assinados pelo provedor

Analisar e serializar JSON novamente pode alterar espaços, ordem, escapes, Unicode ou quebras de linha.

Casos de integração

Implementar um novo endpoint

Converta algoritmo e cabeçalho do provedor em uma lista revisável antes de programar.

Perguntas técnicas

Esta ferramenta verifica um webhook real?

Não. Ela produz etapas e nunca solicita payload, segredo ou assinatura.

Devo enviar o segredo do webhook?

Não. Informe apenas algoritmo e cabeçalho; mantenha o segredo no ambiente protegido.

Quanto custa a solicitação de API?

Cada solicitação custa US$ 0,002. A implementação determinística roda no navegador sem enviar segredos.

Ver a documentação completa do KIT →

Executar grátis

O que uma assinatura HMAC prova

Erros comuns e quando usar a lista

Comece pelos bytes assinados pelo provedor

Reconstrua, calcule e compare na ordem correta

Trate a criptografia como parte da aceitação

Casos de uso

Revisar uma integração existente

Preparar testes de segurança

Perguntas frequentes

Ferramentas relacionadas

Para desenvolvedores — acesso via API

Endpoint

Chame do seu código

Exemplo de requisição

Exemplo de resposta

Preço

Erros

Notas técnicas

Comece pelos bytes assinados pelo provedor

Casos de integração

Implementar um novo endpoint

Perguntas técnicas

obrigado