Il webhook che l'AI ha scritto dai docs si rompe sul primo evento vero

Un handler webhook che passa la review e poi esplode in produzione

C'è un bug ricorrente in chi fa scrivere all'AI i propri gestori di webhook, e nasce da un'abitudine che di per sé è ragionevole. Come racconta l'articolo "Your AI wrote that webhook handler from the docs. The docs are abridged.", il problema è che «la documentazione dei payload è abbreviata di proposito».

Un evento reale di Stripe come payment_intent.succeeded può contare diverse centinaia di righe. Nessuno lo pubblica intero in una guida introduttiva: i docs mostrano una versione tagliata, con i campi più interessanti e dei puntini di sospensione. Perfetta come illustrazione, ingannevole come schema. Il risultato è un handler scritto sull'esempio, non sul traffico vero. Passa la review, corrisponde alla documentazione, e poi il primo evento in produzione arriva con un campo che non c'è e va in errore.

Le forme sono sempre le stesse e prevedibili. La nidificazione che l'esempio aveva appiattito: in Clerk user.created non ha email sull'oggetto utente, ma un array di indirizzi con un puntatore al principale. La differenza tra assente e nullo: metadata che negli esempi è sempre pieno e nella realtà a volte manca del tutto, facendo saltare la riga. I campi espandibili che arrivano come stringa e non come oggetto. E la busta anziché la riga, tipica dei webhook di Supabase, dove il record è dentro record e non nel payload diretto.

Cosa significa se il tuo codice l'ha scritto Bolt

Se hai messo online un'app con Bolt e ti sei affidato al codice generato per gestire un pagamento, un'iscrizione o una sincronizzazione di dati, questa dinamica ti riguarda in pieno. Bolt è ottimo per arrivare a un handler funzionante in pochi minuti, ma quel codice nasce dallo stesso materiale che confonde tutti: la documentazione ufficiale del provider.

Il guaio non è che l'handler vada in crash rumoroso. Nella metà dei casi non lancia alcun errore: scrive undefined nel database e tu te ne accorgi giorni dopo, quando un utente non riceve la conferma o un ordine risulta senza email. Un webhook che fallisce in silenzio è peggio di uno che esplode, perché non compare in nessun alert e intanto corrompe i tuoi dati.

Il secondo problema è la ripetizione. Se Bolt ha generato un pattern sbagliato per un webhook, con ogni probabilità lo ha applicato allo stesso modo a tutti gli altri gestori del progetto. Un errore singolo diventa una classe di errori distribuita nel repository, e nessuna review superficiale la intercetta perché ogni singolo file, preso da solo, sembra corretto.

Perché ora ti serve un audit

Il motivo per cui questi bug sopravvivono è che manca un momento in cui qualcuno guardi il repository nel suo insieme e dica: «ecco dove i tuoi handler assumono uno schema che il provider non garantisce». Tu non hai scritto quel codice riga per riga, quindi non hai la mappa mentale di dove sono le fragilità. L'AI le ha prodotte, ma non te le segnala.

Un audit on-demand come VibeInspect serve esattamente a questo: carichi lo ZIP del repository, specialisti AI lo analizzano e ricevi un PDF con un verdetto. Niente server da configurare, il codice sorgente viene cancellato al termine dell'analisi. Non è un pentest, non corregge il codice e non promette sicurezza assoluta: ti dice in che stato è davvero il tuo repository.

Nel caso dei webhook, il verdetto che ti serve è concreto. Dove l'accesso a campi opzionali avviene senza optional chaining. Dove un handler legge un campo che il provider consegna come stringa trattandolo come oggetto. Dove manca la validazione della firma dell'evento. Dove un payload viene destrutturato assumendo una forma che la documentazione mostrava, ma che il traffico reale non rispetta.

Con il piano Diagnostic ottieni file, riga ed evidenze: sai esattamente quale gestore riscrivere prima che il prossimo evento reale ti scriva undefined nel database. È il livello giusto quando il problema è tecnico e circoscritto come questo, e non un generico «non so in che stato è il progetto».

Cosa un linter non vede

Un linter lavora sulla forma del codice, non sul significato dei dati che ci passano dentro. Vede una variabile non usata, un import mancante, una parentesi fuori posto. Non ha la minima idea di come sia fatto un evento di Stripe, di Clerk o di Supabase.

Un linter non ti dirà mai che evt.data.email restituirà sempre undefined perché quel provider spedisce un array di indirizzi. Non sa che metadata a volte è assente e quindi quella condizione può lanciare Cannot read properties of undefined. Non riconosce che un campo espandibile può arrivare come stringa. Non sa distinguere la busta dal record. Per il linter tutto questo è codice sintatticamente perfetto, e infatti lo è: passa ogni controllo automatico e resta rotto.

Anche gli strumenti di test dei provider ingannano. Un evento sintetico generato dal loro comando è anch'esso idealizzato: non nasce dal tuo account reale. La differenza che ti interessa è proprio quella tra la documentazione e il tuo traffico vero, e nessuno strumento generico la copre. Serve un occhio che ragioni sul contratto tra il tuo codice e i dati che riceve.

Cosa fare questa settimana

Parti da un gesto semplice e a costo quasi zero: cattura un evento reale. Aggiungi nel pannello del tuo provider un secondo endpoint webhook che punti a un servizio che registra le richieste grezze. I provider inviano a tutti gli endpoint configurati, quindi gira in parallelo al tuo handler senza cambiare nulla. Un solo payload vero, catturato prima di scrivere il codice, previene tutti i bug di questa categoria.

Poi confronta quel payload reale con ciò che i tuoi handler assumono, e cerca i quattro schemi: nidificazione appiattita, assente contro nullo, campi espandibili come stringa, busta contro riga.

Infine, per non farlo a occhio su decine di file, carica lo ZIP del repository su VibeInspect e chiedi un audit mirato. Con il piano Diagnostic ricevi file, riga ed evidenze su ogni handler fragile: sai cosa riscrivere prima che il prossimo evento in produzione ti sorprenda.