Cos'è un webhook? Come le app si avvisano a vicenda

Un webhook è un messaggio automatico che un servizio invia alla tua app nel momento esatto in cui succede qualcosa. Quando il pagamento di un cliente va a buon fine, Stripe invia un webhook a un indirizzo della tua app con scritto "pagamento riuscito, ecco i dettagli", e la tua app reagisce — segna l'ordine come pagato, invia la ricevuta, sblocca l'account. In breve: un'API è la tua app che fa una domanda a un altro servizio; un webhook è l'altro servizio che chiama la tua app per dirle qualcosa.

Perché conta quando costruisci con l'AI

Non appena la tua app accetta pagamenti, riceve moduli inviati da un altro strumento o si collega a servizi come GitHub, Shopify o un calendario, incontrerai i webhook. Di solito sono il modo corretto per sapere che qualcosa è successo — ma è anche lì che le app create con l'AI sbagliano più spesso, in modo sottile:

• L'endpoint accetta qualsiasi richiesta, quindi chiunque può inventare un evento "pagamento riuscito".
• L'app concede l'accesso sulla pagina di reindirizzamento del checkout invece che sul webhook, così chi chiude la scheda in anticipo non ottiene ciò che ha pagato, e chi trova l'URL di successo lo ottiene gratis.
• Lo stesso evento arriva due volte e il cliente riceve due ordini o due email.

Sapere come funzionano i webhook ti permette di chiedere le protezioni fin dall'inizio.

Un'analogia quotidiana: il messaggio di consegna

Puoi sapere se il tuo pacco è arrivato in due modi. Puoi continuare ad andare alla porta d'ingresso ogni dieci minuti per controllare (questo è il polling — la tua app che chiama ripetutamente un'API per chiedere "ci sono novità?"). Oppure il corriere può mandarti un messaggio quando consegna (questo è un webhook).

Il messaggio è chiaramente migliore — purché tu possa fidarti. Se chiunque potesse inviarti un messaggio "pacco consegnato", vorresti un modo per sapere che arriva davvero dal corriere. E se il telefono era spento quando è arrivato il messaggio, vorresti che il corriere riprovasse più tardi. Queste due questioni — verifica e nuovi tentativi — sono gran parte di ciò che rende i webhook delicati.

Come funziona un webhook, passo dopo passo

1. Crei un endpoint nel backend della tua app: un URL come https://yourapp.com/webhooks/stripe che accetta richieste POST.
2. Registri quell'URL presso il fornitore e scegli quali eventi ricevere (ad esempio "checkout completato" e "abbonamento annullato").
3. Il fornitore ti dà un segreto di firma. Lo salvi come segreto sul tuo server — vedi variabili d'ambiente e segreti.
4. Succede un evento. Il fornitore invia una richiesta HTTP al tuo URL con un corpo JSON che lo descrive, più un'intestazione di firma.
5. La tua app verifica la firma, registra l'ID dell'evento, risponde rapidamente con un codice di successo (200) e poi svolge il lavoro.
6. Se la tua app non risponde con successo, molti fornitori riprovano più tardi.

Firme

Una firma dimostra che la richiesta arriva dal fornitore e non è stata alterata. Stripe, ad esempio, calcola un HMAC (una sorta di impronta digitale con chiave) con SHA-256 sul corpo della richiesta e su un timestamp, usando il segreto di firma, e lo invia in un'intestazione Stripe-Signature. La tua app esegue lo stesso calcolo con la sua copia del segreto; se i risultati coincidono, la richiesta è genuina. Poiché anche il timestamp è firmato, puoi rifiutare vecchie richieste che qualcuno ha registrato e riprodotto in seguito — secondo la documentazione di Stripe aggiornata a settembre 2026, le librerie di Stripe usano di default una tolleranza di cinque minuti.

Un dettaglio pratico: la firma viene calcolata sul corpo grezzo della richiesta. Se il tuo framework analizza e riformatta il JSON prima della verifica, il controllo fallisce. È un errore molto comune.

Nuovi tentativi, duplicati e ordine

I fornitori differiscono, quindi controlla la documentazione di ciascuno. A settembre 2026:

La documentazione di Stripe dice anche che gli eventi non sono garantiti nell'ordine in cui sono avvenuti, e che lo stesso evento può occasionalmente arrivare più di una volta, quindi consiglia di tenere traccia degli ID degli eventi.

La lezione generale vale per ogni fornitore: gli eventi possono arrivare in ritardo, più di una volta e fuori ordine. Il tuo gestore dovrebbe essere idempotente — elaborare due volte lo stesso evento ha lo stesso effetto che elaborarlo una volta.

Un esempio pratico: sbloccare un corso a pagamento

Vendi un corso online. Uno studente clicca Acquista, paga sulla pagina di checkout ospitata da Stripe e torna al tuo sito.

Il modo fragile: la pagina "grazie" sblocca il corso. Se lo studente chiude il browser durante il reindirizzamento, ha pagato ma non ha accesso. Se qualcuno indovina l'URL della pagina "grazie", ottiene l'accesso senza pagare.

Il modo con il webhook:

1. Quando Stripe conferma il pagamento, invia un evento checkout.session.completed a /webhooks/stripe.
2. Il tuo backend verifica la firma con il segreto di firma. Se fallisce, risponde 400 e non fa nulla.
3. Controlla se quell'ID evento è già stato elaborato. Se sì, risponde 200 e si ferma.
4. Salva l'ID dell'evento, risponde 200, poi concede l'accesso allo studente e invia un'email di benvenuto.
5. La pagina "grazie" dice semplicemente "Pagamento ricevuto — il tuo corso comparirà a breve" e controlla lo stato di accesso dello studente.

Più tardi, se un abbonamento viene annullato o una carta viene rifiutata, altri eventi webhook dicono alla tua app di rimuovere o sospendere l'accesso. È così che i prodotti in abbonamento restano sincronizzati con la fatturazione — vedi cos'è il SaaS e come aggiungere i pagamenti alla tua app.

Termini chiave

• Endpoint: l'URL della tua app che riceve i webhook.
• Evento / payload: cosa è successo, e i dati che lo descrivono (di solito JSON).
• Segreto di firma: il segreto condiviso usato per verificare le firme.
• Idempotente: sicuro da eseguire più volte con lo stesso risultato.
• Polling: chiedere ripetutamente a un'API le modifiche invece di aspettare un webhook.
• Tunnel: uno strumento che dà a un portatile un URL pubblico temporaneo così i webhook possono raggiungerlo durante lo sviluppo.

Errori comuni e false convinzioni

• Non verificare le firme. L'URL dell'endpoint non è un segreto. È la verifica che rende la richiesta affidabile.
• Fare lavoro lento prima di rispondere. Inviare email o generare PDF prima di rispondere può causare timeout, che innescano nuovi tentativi, che causano duplicati.
• Supporre una consegna esattamente una volta, in ordine. Registra gli ID degli eventi e non contare sull'ordine di arrivo.
• Usare un URL di anteprima. I webhook richiedono un indirizzo pubblico stabile. Le anteprime private e localhost non sono raggiungibili da internet; usa l'URL pubblicato (o un tunnel durante i test).
• Mescolare segreti di test e live. I fornitori spesso emettono segreti di firma diversi per la modalità test e quella live. Conservali entrambi e usa quello giusto.
• Fidarsi ciecamente del payload per decisioni importanti. Per azioni ad alto rischio, è ragionevole recuperare lo stato più recente dall'API del fornitore dopo aver ricevuto l'evento.

Cosa chiedere al tuo AI builder

Aggiungi un endpoint POST /webhooks/stripe sul server. Verifica la firma Stripe usando il corpo grezzo della richiesta e il segreto STRIPE_WEBHOOK_SECRET. Rifiuta le firme non valide con 400. Salva ogni ID evento e salta gli eventi già elaborati. Rispondi 200 rapidamente, poi gestisci checkout.session.completed segnando l'ordine come pagato e inviando la ricevuta. Registra il tipo di evento. Non concedere l'accesso dalla pagina di successo del checkout.

Poi testalo: invia un evento di prova dalla dashboard del fornitore, inviane di nuovo lo stesso, e invia una richiesta con una firma sbagliata. Solo il primo dovrebbe cambiare qualcosa.

I webhook su Mythex

Mythex non gestisce un servizio webhook separato; chiedi all'agente di aggiungere un endpoint webhook nel backend della tua app e di puntare il fornitore al tuo URL pubblicato, perché i webhook richiedono un indirizzo pubblico. Il segreto di firma va nei segreti del progetto, e se lo cambi su un'app live, pubblica di nuovo. La ricetta della documentazione su gestire i webhook include un prompt di partenza, e i template per negozi sono un buon punto di partenza per le app che accettano pagamenti.

Domande