Validador de assinatura de webhook

Cole uma assinatura que falha

Os quatro esquemas de assinatura

Os quatro são HMAC, mas diferem no que é hasheado e em como o resultado é codificado. Um detalhe errado e toda entrega falha.

O Twilio é a exceção — ele hasheia uma URL canônica mais parâmetros ordenados, não o corpo. Use o validador de assinatura do Twilio para isso.

As cinco causas reais

Ordenadas por quanto aparecem em threads de suporte.

A armadilha do corpo bruto

A causa número um: você verifica contra o corpo parseado-e-re-serializado em vez dos bytes exatos. JSON.stringify(JSON.parse(body)) muda espaçamento e ordem das chaves, então o HMAC não bate mais. Leia o corpo bruto antes de qualquer coisa parseá-lo.

// Express: keep the RAW bytes, do NOT let JSON re-serialise them
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body;                 // Buffer, exactly as received
  verify(raw, req.headers['stripe-signature'], secret);
});

# Flask: request.get_data() returns the raw body; request.json does NOT
raw = request.get_data()               # bytes, untouched
verify(raw, request.headers['X-Hub-Signature-256'], secret)

// Next.js App Router: read the text before parsing
export async function POST(req) {
  const raw = await req.text();         // sign THIS, not JSON.stringify(await req.json())
  verify(raw, req.headers.get('stripe-signature'), secret);
}

Regra prática: capture a assinatura e os bytes brutos na borda, verifique, depois parseie.

Timestamps e replays

Stripe e Slack embutem um timestamp na string assinada e rejeitam o que passa de cinco minutos — é proteção contra replay, não um bug. GitHub e Shopify não, então uma assinatura GitHub válida continua válida para sempre. Se a ferramenta diz válida mas expirada, seu secret e corpo estão bem; você só está reenviando um evento antigo. Gere uma entrega nova em vez de reenviar uma capturada.

Quando a assinatura confere

Precisa enviar um evento de teste corretamente assinado ao seu endpoint? O assinador de webhooks monta um para os seis provedores. Para capturar e inspecionar entregas reais, aponte-as para um túnel Relay.

Perguntas frequentes