Webhooks

Il polling API prevede che il sistema ricevente chieda ripetutamente al sistema sorgente "è cambiato qualcosa?" a intervalli fissi (ogni 1 minuto, ogni 5 minuti). Questo è inefficiente: la maggior parte delle richieste di polling restituisce "nessuna modifica", consumando la quota API e creando latenza (la latenza massima è uguale all'intervallo di polling). I webhook invertono il modello: il sistema sorgente notifica il ricevitore nell'istante in cui si verifica un evento, raggiungendo una latenza quasi zero senza chiamate API sprecate. La limitazione è l'affidabilità: i webhook sono "fire and forget" per impostazione predefinita — se il sistema ricevente è inattivo, gli eventi vengono persi. I sistemi di webhook ben progettati aggiungono una logica di retry con exponential backoff (tentando la consegna più volte a intervalli crescenti) e log di consegna (visibili nell'interfaccia utente del prodotto in modo che i clienti possano verificare se il loro endpoint ha ricevuto ogni evento e indagare sui fallimenti).

I fallimenti dei webhook sono tra i ticket di supporto per l'integrazione più complessi perché coinvolgono entrambi i lati dell'integrazione. Scenari comuni: (1) L'endpoint non riceve eventi — verificare che l'URL dell'endpoint sia pubblicamente accessibile (non localhost), che il server abbia accettato l'evento di test e che il tipo di evento sia sottoscritto. (2) Risposta HTTP 200 non restituita — il server ricevente deve restituire uno stato HTTP 200 entro la finestra di timeout (tipicamente 10–30 secondi); se impiega più tempo, la piattaforma webhook contrassegna la consegna come fallita anche se il server ha poi elaborato l'evento. (3) Eventi duplicati — i consumer di webhook ben progettati dovrebbero essere idempotenti (l'elaborazione dello stesso evento due volte produce lo stesso risultato dell'elaborazione una sola volta) utilizzando l'ID univoco dell'evento per rilevare e ignorare i duplicati. (4) Verifica della firma fallita — la maggior parte delle API SaaS firma i payload dei webhook con HMAC-SHA256 utilizzando una chiave segreta; il codice del cliente deve verificare questa firma su ogni evento ricevuto per prevenire attacchi di webhook spoofing.

Product Ops collabora con l'ingegneria per progettare funzionalità webhook che minimizzino il carico di supporto e massimizzino la soddisfazione degli sviluppatori. Best practice: copertura dei tipi di evento (ogni cambiamento di stato significativo nel prodotto dovrebbe avere un evento webhook corrispondente); progettazione del payload dell'evento (i payload dovrebbero includere tutti i dati necessari per agire sull'evento senza una successiva chiamata API — includere lo stato completo dell'oggetto, non solo gli ID che richiedono una successiva richiesta GET); UI dei log di consegna (un log di eventi ricercabile nella dashboard del prodotto dove gli sviluppatori possono vedere ogni evento attivato, il suo stato di consegna, la risposta HTTP del server e un pulsante "redeliver" per il retry manuale); verifica della firma (firmare ogni payload con HMAC-SHA256 e documentare chiaramente il processo di verifica); e payload versionati (quando lo schema dell'evento deve cambiare, versionare il payload e supportare entrambe le versioni contemporaneamente durante un periodo di transizione — non apportare mai modifiche che interrompano la compatibilità a un payload webhook senza preavviso).