Verificação de assinatura de webhook da Stripe falhou — descubra por quê

Depure a sua assinatura da Stripe

A Stripe vem selecionada por padrão. O HMAC é calculado no seu navegador com WebCrypto — o seu whsec_ nunca sai da aba.

Anatomia do cabeçalho Stripe-Signature

Todo webhook da Stripe chega com um cabeçalho parecido com este. Cada campo separado por vírgula tem uma função:

Stripe-Signature: t=1614556800,
  v1=5257a869e7ecebeda32affa62cdca3fa51cad7414a563a8c6e3c4b41c2b7f2c8,
  v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

A string assinada é `${t}.${rawBody}` — não o corpo sozinho. Esqueça o prefixo t. em um verificador feito à mão e toda assinatura falha, mesmo com o secret certo.

As 6 causas raiz, na ordem em que verificar

Ordenadas pela frequência com que são as culpadas. Cada uma tem um sinal que a distingue das outras.

A correção do corpo bruto, framework por framework

A causa nº 1 é quase sempre esta: o seu framework web leu, parseou e re-serializou o JSON antes de o constructEvent vê-lo. JSON re-serializado tem espaçamento diferente, então o HMAC deixa de bater. Veja como entregar a cada framework os bytes intactos.

// A rota do webhook PRECISA vir antes do express.json()
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);
app.use(express.json()); // todo o resto

export async function POST(req: Request) {
  const body = await req.text();            // bruto, intacto
  const sig = req.headers.get('stripe-signature')!;
  const event = stripe.webhooks.constructEvent(
    body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

import { buffer } from 'micro';
export const config = { api: { bodyParser: false } };

export default async function handler(req, res) {
  const raw = await buffer(req);
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(
    raw, sig, process.env.STRIPE_WEBHOOK_SECRET
  );
  res.json({ received: true });
}

Cole os bytes exatos no depurador acima: se a assinatura só bate depois de remover uma quebra de linha final ou um campo recodificado, o corpo foi alterado no caminho — o problema não é o seu secret.

Modo teste vs modo live: o secret que parece certo, mas não é

A Stripe te entrega três valores whsec_ diferentes, e é fácil confundi-los. Primeiro, o secret do endpoint de teste, mostrado no Dashboard enquanto você está em modo teste. Segundo, o secret do endpoint live — um valor separado no mesmo endpoint passado para live. Terceiro, o secret da CLI que o stripe listen imprime, diferente de novo e válido apenas para os eventos encaminhados por aquela sessão. Os três produzem um HMAC de aparência válida, então o erro é o mesmo No signatures found genérico — nada diz modo trocado. O sinal: pagamentos de teste verificam, os reais dão 400. Correção: leia o secret do endpoint exato, no modo exato, que está recebendo o tráfego.

A janela de replay de 5 minutos que todo mundo esquece

O constructEvent não verifica só o HMAC — ele rejeita qualquer evento cujo timestamp t= tenha mais de 300 segundos, lançando Timestamp outside the tolerance zone. Isso pega quando você reenvia um evento capturado horas depois, ou quando o relógio do servidor saiu de sincronia. A assinatura é perfeitamente válida; o que falha é a idade. O depurador acima mostra a idade do timestamp para você distinguir um replay velho de uma assinatura realmente divergente. Se você precisa mesmo de uma janela maior, o constructEvent aceita um quarto argumento tolerance em segundos — mas corrija o relógio primeiro.

É o seu handler ou o seu secret? Gere um evento sabidamente válido

Quando o depurador diz que o secret está certo mas a produção continua dando 400, o bug está em como o seu handler lê o corpo. Isole-o: o nosso Signer gera um payload assinado no formato da Stripe com um secret que você controla, para você fazer POST de um evento garantidamente válido direto no seu handler local. Se passar, o seu código de verificação está certo e o problema é o secret ou o middleware. Se falhar, o handler está alterando o corpo — volte à tabela do corpo bruto acima.

Checklist de diagnóstico

Siga esta ordem na próxima vez que o constructEvent lançar um erro.

1. Cole o whsec_, o corpo bruto e o Stripe-Signature que falham no depurador acima — ele aponta a causa antes de você continuar lendo.
2. Confirme que o corpo que chega ao constructEvent é a string bruta intacta, não um objeto parseado e re-serializado.
3. Copie o signing secret direto da página do endpoint no Dashboard — não do stripe listen, nem de outro endpoint.
4. Verifique se você usa o secret live para o tráfego live e o secret de teste para o tráfego de teste.
5. Registre req.headers['stripe-signature'] no log e confirme que ele está presente e não foi truncado por um proxy.
6. Verifique se o timestamp t= do evento não tem mais de 5 minutos (replay velho ou relógio fora de sincronia).

Capture e reenvie o evento real que falha

Ainda travado? Aponte a Stripe para um Relay ou uma URL de captura do Webhook Toolkit, pegue a requisição exata que está falhando e inspecione o corpo bruto e os cabeçalhos byte a byte — depois reenvie-a ao seu handler quantas vezes precisar, sem esperar outro evento real.

Perguntas frequentes