Stripe webhook non funziona: guida completa per debug e fix 2026

Stripe webhook non funziona: cosa significa davvero?

Se il tuo webhook Stripe non funziona, non sei il solo.
È uno dei problemi più comuni nello sviluppo di SaaS, API e piattaforme digitali.

👉 Spesso il problema non è Stripe, ma come gestisci gli eventi lato backend.

Un webhook non funzionante significa che:

• il pagamento può essere completato
• ma il tuo sistema non riceve o non gestisce correttamente l’evento

E questo può causare:

• utenti senza accesso
• stato incoerente
• perdita di fatturato

Perché il webhook Stripe non funziona 🔍

Le cause più comuni sono:

• ❌ Body parser che modifica la richiesta
• ❌ Secret webhook errato
• ❌ Confusione tra ambiente test e live
• ❌ Endpoint non raggiungibile
• ❌ Eventi gestiti male (ritorni 200 senza logica)

👉 Il problema più frequente è questo:

Il tuo server risponde 200 OK, ma non fa nulla davvero

Stripe quindi:

• pensa che tutto sia ok
• smette di fare retry
• il sistema resta desincronizzato

Errori più comuni nella gestione dei webhook

Molti sviluppatori commettono questi errori:

• affidarsi a express.json() invece di express.raw()
• non verificare la firma del webhook
• non gestire eventi duplicati
• non salvare gli eventi ricevuti
• usare solo il redirect frontend

Questo porta direttamente al problema: pagamento Stripe riuscito ma utente senza accesso

👉 Leggi anche: Pagamento Stripe riuscito ma utente senza accesso: cosa fare

Come fare debug dei webhook Stripe 🛠️

Per capire perché un webhook Stripe non funziona, segui questo processo:

1. Controlla la dashboard Stripe

Vai su:
👉 Developers → Events

Verifica:

• se l’evento è stato inviato
• se è fallito
• eventuali errori HTTP

2. Verifica i log backend

Controlla:

• se la richiesta arriva
• se fallisce la signature
• se il codice viene eseguito

3. Usa il replay degli eventi

Stripe permette di reinviare eventi:
👉 utilissimo per debug

4. Controlla il webhook secret

Errore comune:

• usare secret sbagliato (test vs live)

Esempio corretto (Node.js Express) 💻

app.post('/webhook/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    console.error('❌ Signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  console.log('📩 Stripe event received:', event.type, event.id);

  try {
    switch (event.type) {
      case 'checkout.session.completed':
        const session = event.data.object;

        console.log('✅ Payment completed for:', session.customer_email);

        // TODO: aggiorna utente
        // grantAccessToUser(session.customer_email);

        break;

      case 'invoice.payment_failed':
        console.warn('⚠️ Payment failed event received');
        break;

      default:
        console.log('ℹ️ Unhandled event type:', event.type);
    }

  } catch (processingError) {
    console.error('❌ Error processing event:', processingError);
    return res.status(500).send('Processing error');
  }

  res.status(200).send();
});

app.post('/webhook/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    console.error('❌ Signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  console.log('📩 Stripe event received:', event.type, event.id);

  try {
    switch (event.type) {
      case 'checkout.session.completed':
        const session = event.data.object;

        console.log('✅ Payment completed for:', session.customer_email);

        // TODO: aggiorna utente
        // grantAccessToUser(session.customer_email);

        break;

      case 'invoice.payment_failed':
        console.warn('⚠️ Payment failed event received');
        break;

      default:
        console.log('ℹ️ Unhandled event type:', event.type);
    }

  } catch (processingError) {
    console.error('❌ Error processing event:', processingError);
    return res.status(500).send('Processing error');
  }

  res.status(200).send();
});

👉 Questo è fondamentale:
usa sempre express.raw() per i webhook Stripe

Best practice per evitare problemi 🧩

Per evitare che il webhook Stripe non funzioni:

• ✔️ rendi il sistema idempotente
• ✔️ salva ogni evento ricevuto
• ✔️ gestisci retry Stripe
• ✔️ non fidarti del frontend
• ✔️ verifica sempre la firma

Per un consulto tecnico sui webhook Stripe, consigliamo di visionare le docs ufficiali Stripe Webhook.

Un approccio più strutturato (consigliato)

Nei progetti più complessi, la gestione dei webhook viene separata dal resto dell’applicazione.

Questo permette di:

• centralizzare la gestione eventi
• mantenere sincronizzato lo stato utenti
• ridurre bug e inconsistenze

Alcuni team costruiscono sistemi interni, altri utilizzano strumenti dedicati.

Ad esempio:

• Stripe fornisce la base per la gestione degli eventi
• piattaforme di automazione aiutano nella gestione dei flussi
• servizi come Licenzy permettono di gestire entitlements, accesso e sincronizzazione dei webhook Stripe, evitando di dover implementare manualmente tutta la logica di access control lato backend

👉 Questo approccio riduce drasticamente errori legati a logiche duplicate e gestione manuale degli eventi.

Errori da evitare assolutamente ❌

Ci sono alcuni errori da evitare se vuoi che uno Stripe webhook funzioni:

• abilitare accesso via redirect frontend
• non verificare webhook
• ignorare eventi falliti
• non gestire duplicati
• non avere log

Conclusione

Se il tuo Stripe webhook non funziona, il problema è quasi sempre nella gestione lato backend.

👉 Non è un bug di Stripe
👉 È una questione di architettura

Impostare correttamente:

• webhook
• stato utenti
• gestione eventi

è fondamentale per evitare problemi che possono costarti utenti e ricavi.

FAQ ❓