Verifica della firma webhook Stripe fallita — scopri perché

Fai il debug della tua firma Stripe

Stripe è selezionato di default. L'HMAC viene calcolato nel tuo browser con WebCrypto — il tuo whsec_ non lascia mai la scheda.

Anatomia dell'header Stripe-Signature

Ogni webhook Stripe arriva con un header che assomiglia a questo. Ogni campo separato da virgola ha un compito:

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

La stringa firmata è `${t}.${rawBody}` — non il body da solo. Dimentica il prefisso t. in un verificatore scritto a mano e ogni firma fallisce, anche con il secret giusto.

Le 6 cause alla radice, nell'ordine in cui controllarle

Ordinate per frequenza. Ognuna ha un indizio che la distingue dalle altre.

La correzione del body grezzo, framework per framework

La causa n. 1 è quasi sempre questa: il tuo framework web ha letto, parsato e ri-serializzato il JSON prima che constructEvent lo vedesse. Il JSON ri-serializzato ha spazi diversi, quindi l'HMAC non corrisponde più. Ecco come passare a ogni framework i byte intatti.

// La route del webhook DEVE venire prima di 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()); // tutto il resto

export async function POST(req: Request) {
  const body = await req.text();            // grezzo, intatto
  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 });
}

Incolla i byte esatti nel debugger qui sopra: se la firma corrisponde solo dopo aver tolto un a capo finale o un campo ricodificato, il body è stato modificato in transito — non è il tuo secret.

Test mode vs live mode: il secret che sembra giusto ma non lo è

Stripe ti dà tre valori whsec_ diversi ed è facile confonderli. Primo, il secret dell'endpoint di test, mostrato nella Dashboard quando sei in test mode. Secondo, il secret dell'endpoint live — un valore separato sullo stesso endpoint passato in live. Terzo, il secret della CLI che stampa stripe listen, ancora diverso e valido solo per gli eventi inoltrati da quella sessione. Tutti e tre producono un HMAC dall'aspetto valido, quindi l'errore è sempre il generico No signatures found — niente dice modalità sbagliata. L'indizio: i pagamenti di test si verificano, quelli reali danno 400. Soluzione: leggi il secret dall'endpoint esatto, nella modalità esatta, che riceve il traffico.

La finestra anti-replay di 5 minuti che tutti dimenticano

constructEvent non controlla solo l'HMAC — rifiuta qualsiasi evento il cui timestamp t= abbia più di 300 secondi, lanciando Timestamp outside the tolerance zone. Ti colpisce quando rinvii un evento catturato ore dopo, o quando l'orologio del tuo server è sfasato. La firma è perfettamente valida; è l'età a far fallire il controllo. Il debugger qui sopra mostra l'età del timestamp, così distingui un replay scaduto da una vera discrepanza di firma. Se ti serve davvero una finestra più lunga, constructEvent accetta un quarto argomento tolerance in secondi — ma prima sistema l'orologio.

È il tuo handler o il tuo secret? Genera un evento sicuramente valido

Quando il debugger dice che il secret è giusto ma la produzione dà ancora 400, il bug sta nel modo in cui il tuo handler legge il body. Isolalo: il nostro Signer genera un payload firmato Stripe con un secret che controlli tu, così puoi inviare in POST un evento sicuramente valido direttamente al tuo handler locale. Se passa, il tuo codice di verifica è a posto e il problema è il secret o il middleware. Se fallisce, l'handler sta modificando il body — torna alla tabella del body grezzo qui sopra.

Checklist di diagnosi

Esegui questi controlli in ordine la prossima volta che constructEvent lancia un'eccezione.

1. Incolla nel debugger qui sopra il whsec_, il body grezzo e lo Stripe-Signature che falliscono — ti dà la causa prima che tu legga oltre.
2. Verifica che il body che arriva a constructEvent sia la stringa grezza intatta, non un oggetto parsato e ri-serializzato.
3. Copia il secret di firma direttamente dalla pagina dell'endpoint nella Dashboard — non da stripe listen, non da un altro endpoint.
4. Verifica di usare il secret live per il traffico live e il secret di test per il traffico di test.
5. Logga req.headers['stripe-signature'] e verifica che sia presente e non troncato da un proxy.
6. Verifica che il timestamp t= dell'evento non abbia più di 5 minuti (replay scaduto o orologio sfasato).

Cattura e riesegui il vero evento che fallisce

Ancora bloccato? Punta Stripe su un Relay o su un URL di cattura di Webhook Toolkit, intercetta la richiesta esatta che fallisce e ispeziona body grezzo e header byte per byte — poi rieseguila sul tuo handler tutte le volte che vuoi, senza aspettare un altro evento live.

Domande frequenti