Webhook vs API polling: quale scegliere per le tue integrazioni (2021)

Le integrazioni SaaS nel 2021 sono diventate un problema operativo

Nel 2021 la PMI italiana media non lavora più con un solo gestionale: usa un CRM sul cloud, una piattaforma e-commerce, un sistema di fatturazione elettronica, uno strumento di customer support, un’app di project management, una suite di marketing automation e quasi sempre un ERP on-premise sopravvissuto da prima della migrazione. Secondo gli osservatori pubblicati nel 2021 (Productiv, Okta), l’azienda B2B sotto i 500 dipendenti utilizza in media tra 50 e 80 applicazioni SaaS distinte, e il numero cresce del 30% annuo. Ogni applicazione è un silos di dati che deve dialogare con almeno tre o quattro altre per non costringere gli operatori al copia-incolla manuale.

A quel volume il problema dell’integrazione diventa il problema. Lo affronti in due modi: o fai polling sulle API delle altre piattaforme (interroghi periodicamente “ci sono novità?”), o ricevi un webhook, cioè una notifica HTTP che parte automaticamente quando qualcosa cambia dall’altra parte. Entrambe le strade funzionano, ma scegliere male significa pagare in tre modi: banda sprecata, dati in ritardo, o integrazioni fragili che si rompono ogni cambio di rete.

In questa guida confronto polling e webhook nel concreto, con esempi 2021 da Stripe webhooks, Shopify, GitHub e da progetti reali in PMI italiane. Vedrai quando preferire uno o l’altro, come implementare la sicurezza con HMAC SHA-256, come gestire idempotency e retry, e una roadmap di 60 giorni per migrare da polling a webhook senza incidenti.

Cos’è l’API polling e come funziona

Il polling è il pattern più antico e semplice delle integrazioni: ogni X minuti il tuo software esegue una chiamata HTTPS verso un endpoint REST del fornitore e chiede “dammi tutto quello che è successo dall’ultimo controllo”. L’endpoint risponde con un payload JSON contenente gli eventi nuovi, e tu li processi.

Meccanismo: intervallo, cursore, rate limiting

Un job di polling ben fatto memorizza un cursore (timestamp updated_at o id autoincrementale, o opaque token restituito dall’API) e a ogni chiamata lo invia per ottenere solo i delta. Esempio classico: GET /orders?since=2021-09-03T14:23:45Z, ricevi solo gli ordini cambiati dopo quel timestamp.

Il problema è il rate limit: tutte le API serie 2021 ne hanno uno. Shopify dà 2 req/sec per shop con leaky bucket, HubSpot 100 req in 10 secondi, GitHub 5000 req/ora autenticate. Se hai 15 integrazioni con polling ogni minuto su 20 endpoint diversi, fai 4320 chiamate/ora su una sola API — il 99% torna vuoto perché nulla è cambiato. Spreco di banda, rate limit saturato, latenza media pari a metà dell’intervallo.

Quando il polling resta la scelta giusta

• API senza webhook: ERP legacy, gestionali on-premise, sistemi bancari corporate, parecchi vecchi portali italiani espongono solo REST in lettura. Non hai alternativa.
• Dati a bassa frequenza con tolleranza al ritardo: listini che cambiano una volta al giorno, anagrafiche, tabelle di lookup. Polling notturno alle 03:00, fine.
• Ambienti di rete restrittivi: se sei dietro firewall corporate senza endpoint pubblico, ricevere webhook è complicato. Il polling parte da te verso l’esterno, attraversa il NAT, non richiede aperture inbound.

Cos’è un webhook e perché ha cambiato le integrazioni

Un webhook è un HTTP callback: configuri presso il fornitore (Stripe, Shopify, GitHub) un URL HTTPS pubblico del tuo sistema; quando succede un evento — ordine creato, pagamento riuscito, ticket chiuso — il fornitore invia un POST al tuo URL con un payload JSON.

Mentre il polling è pull, il webhook è push. L’evento ti arriva nel momento esatto in cui accade, non al prossimo tick. Se Stripe Checkout completa un pagamento alle 16:24:00, alle 16:24:01 il tuo backend ha già ricevuto checkout.session.completed e aggiornato il database. Nessuna chiamata sprecata, latenza sub-secondo.

Anatomia del payload

Un payload webhook contiene almeno: tipo evento (order.created, invoice.paid), timestamp, oggetto modificato. Quasi sempre un event_id univoco — fondamentale per l’idempotency — e una firma HMAC negli header HTTP. Stripe invia Stripe-Signature con timestamp e firma HMAC SHA-256 calcolata sul body, così puoi rifiutare richieste non firmate.

Per il modello concettuale ne avevo parlato a marzo in cos’è un webhook: qui mi concentro sul confronto operativo con il polling.

Confronto tecnico: latenza, banda, complessità, retry

Latenza end-to-end

Polling: latenza media = intervallo / 2. Polling ogni 5 minuti significa 150 secondi medi, 300 secondi nel caso peggiore. Webhook: 200-1500 ms end-to-end con piattaforme mature come Stripe o Shopify.

Costo banda e chiamate

Shop con 200 ordini al giorno e polling ogni 5 minuti: 288 chiamate per intercettare 200 eventi, 88 a vuoto (30%). Stesso shop con webhook: 200 richieste in entrata, zero a vuoto, -69% di traffico API.

Complessità di implementazione

Polling: triviale. Scheduler, HTTP client, cursore, parser. Due ore. Webhook: serve endpoint pubblico HTTPS, validazione firma, parsing, storage idempotency, queue, DLQ. Due-tre giorni, ma il framework è poi riutilizzabile.

Retry policy

Polling: se la chiamata fallisce, riprovi al ciclo successivo. Webhook: è il fornitore a riprovare se rispondi 5xx o vai in timeout. Stripe webhooks riprova per 3 giorni con exponential backoff, GitHub 8 ore, Shopify 48 ore con 19 tentativi. Tu devi garantire che l’endpoint sia idempotente: stesso evento ricevuto due volte non deve produrre due ordini.

Quando preferire polling: tre scenari concreti

API legacy senza webhook

Gestionali italiani on-premise (TeamSystem Polyedro, Zucchetti, Esa Software, Mago.NET) espongono API REST o SOAP in lettura ma non eventi push. Polling intelligente: usa If-Modified-Since o ETag per ridurre traffico, batchifica le query (500 record alla volta, non 50), valuta change data capture direttamente sul database se hai accesso SQL.

Dati a bassissima frequenza

Listini fornitori settimanali, cambi valuta, indici ISTAT, codici tributo. Configurare un webhook per dati che cambiano una volta al mese è overkill, e spesso quelle fonti non li offrono.

Reti corporate restrittive

Sistema dietro firewall enterprise senza traffico inbound. Soluzione 2021 pulita: polling outbound, o strumenti tipo Hookdeck (lanciato nel 2020) come proxy webhook con connessione persistente in uscita verso il tuo backend.

Quando preferire webhook: real-time, volumi alti, cross-SaaS

Pagamenti, ordini, ticket

Se vendi online con Stripe webhooks, PayPal IPN, Adyen, devi processare payment_intent.succeeded in tempo reale per fatturare, decrementare il magazzino, mandare la conferma. Cinque minuti di ritardo = ticket di supporto, contestazioni, chargeback. Stesso ragionamento per i ticket di customer service: se Zendesk o Freshdesk creano un ticket, il tuo CRM lo deve vedere nel secondo successivo.

Volumi alti

Quando hai migliaia di eventi al giorno su una integrazione, il polling diventa proibitivo: o riduci l’intervallo (e aumenti latenza), o lo aumenti (e saturi il rate limit). I webhook scalano col volume reale di eventi, non con i “controlli vuoti”.

Cross-SaaS via orchestratori

Piattaforme come Zapier, Integromat, n8n self-hosted, Pipedream hanno i webhook come input nativo. Configuri “quando Stripe registra un pagamento” e l’orchestratore propaga: crea cliente HubSpot, fattura in Fatture in Cloud, Slack al commerciale. Confronto delle tre piattaforme in Zapier vs Integromat vs n8n.

Il pattern hybrid: webhook + polling di backup

In produzione per integrazioni mission-critical il pattern vincente è entrambi. Webhook come canale primario real-time. Polling ogni 6-12 ore come riconciliazione, che recupera tutti gli eventi delle ultime 24 ore e verifica che nessuno sia perso.

Perché serve? I webhook possono essere persi: il fornitore può smettere di riprovare oltre un limite, l’endpoint può essere down durante un deploy, una richiesta può fallire la firma per mismatch durante rotazione chiavi. Una riconciliazione notturna cattura questi edge case e garantisce eventual consistency. La maggior parte delle implementazioni Stripe in produzione include un job notturno su GET /v1/events?created[gte]=<24h_ago>.

Implementare un webhook robusto: la checklist 2021

HTTPS obbligatorio

Webhook su HTTP plaintext = suicidio: chiunque sniffi il traffico vede payload e firme. Tutti i provider seri (Stripe, Shopify, GitHub) rifiutano endpoint non HTTPS in produzione. Let’s Encrypt, TLS 1.2 minimo, TLS 1.3 quando il client lo supporta.

Validazione firma HMAC

Ogni webhook serio firma il payload con shared secret e HMAC SHA-256. Il tuo endpoint deve:

1. Estrarre la firma dall’header (Stripe-Signature, X-Hub-Signature-256 per GitHub, X-Shopify-Hmac-Sha256).
2. Ricalcolare l’HMAC sul body raw (mai sul body deserializzato e riserializzato — l’ordine dei campi JSON rompe la firma).
3. Confrontare con funzione constant-time per evitare timing attack (hash_equals() in PHP, crypto.timingSafeEqual() in Node).
4. Rifiutare con 401 se la firma non corrisponde.

Dettagli nella guida ad API security best practice 2021.

Idempotency: la regola d’oro

I webhook arrivano duplicati. Sempre. Stripe lo dichiara esplicitamente: “your endpoint should be designed to be idempotent”. Ogni evento ha un event_id, e il primo step del tuo handler deve essere: ho già processato questo event_id? Se sì, rispondi 200 OK e non fare nulla. Se no, scrivi un record in processed_events(event_id PRIMARY KEY, processed_at) in transazione con il lavoro vero. Il vincolo di primary key ti garantisce a livello database che non potrai processarlo due volte. Pattern universale: idempotency-key header lo trovi in Stripe, Square, Plaid.

Retry e backoff

Mai rispondere 200 se non hai effettivamente processato l’evento: il fornitore non riproverà più. Mai rispondere 4xx per errori transienti: il fornitore non riproverà perché interpreta 4xx come “sei sbagliato tu”. Usa 5xx per dire “riprova”, e processa con coda interna (RabbitMQ, AWS SQS, GCP Pub/Sub, Azure Event Grid, o worker Redis) per ack-are subito al fornitore con 200 e processare in background con tuoi retry e exponential backoff.

Dead letter queue

Eventi che falliscono N volte (es. 5 tentativi con backoff) non vanno buttati: mandali in DLQ (dead letter queue), coda separata per intervento umano. Un job di monitoring controlla la lunghezza della DLQ e ti alerta se cresce — segnale che qualcosa di sistemico si è rotto.

Implementare polling efficiente: backoff, ETag, cursore

Exponential backoff su errori

Se l’API risponde 429 (rate limit) o 503, non ricominciare al ciclo successivo: aumenta progressivamente l’intervallo (1, 2, 4, 8, max 30 min) finché non torna 2xx. Onora sempre Retry-After se presente.

Conditional requests con ETag e Last-Modified

Molte API supportano If-None-Match: <etag> e If-Modified-Since. Se la risorsa non è cambiata, risposta 304 Not Modified senza body — banda risparmiata. Per dataset grossi è un acceleratore enorme.

Cursore persistente con safety watermark

Salva il cursore in una tabella dedicata, non in memoria. Aggiungi un safety watermark: invece di ripartire dall’ultimo timestamp esatto, sottrai 30 secondi per coprire eventi out-of-order (comuni in API distribuite). La deduplica per ID lato tuo gestisce gli eventi visti due volte.

Cursor-based pagination, non offset

Per dataset grossi evita ?page=1&per_page=50: la offset pagination si rompe se i dati cambiano fra una pagina e l’altra. Usa cursor-based (?after=<opaque_token>) — vedi REST API design best practice 2021.

Sicurezza dei webhook nel 2021: HMAC, IP whitelist, JWT

Layer 1: firma HMAC SHA-256

Shared secret + HMAC SHA-256 sul body + confronto constant-time. Difesa principale non negoziabile. Senza firma valida, 401.

Layer 2: IP whitelist

Alcuni fornitori pubblicano i range IP. GitHub pubblica i meta endpoint, Stripe ha una lista documentata ma raccomanda di non basarsi solo su quella. L’IP whitelisting a livello firewall o reverse proxy blocca scanner random — non sostituisce la firma HMAC, la integra.

Layer 3: replay protection con timestamp

La firma HMAC non impedisce che un attaccante intercetti una richiesta valida e la rigiochi ore dopo. Stripe aggiunge un timestamp nel payload firmato: il tuo endpoint rifiuta richieste più vecchie di 5 minuti. Implementa lo stesso check ovunque puoi.

Layer 4: JWT per webhook interni

Quando il fornitore del webhook è un tuo microservizio interno, usa JWT firmati con RS256: il chiamante firma con chiave privata, il ricevente verifica con la pubblica. Niente shared secret da rotare manualmente. Vedi microservizi vs monolite.

Strumenti 2021 per webhook e polling: il toolkit

Testing e sviluppo locale

• ngrok: tunnel che espone localhost:3000 su URL HTTPS pubblico. Indispensabile per testare webhook in dev.
• Webhook.site: URL pubblico che logga tutte le richieste con headers e body. Ispeziona cosa ti manda un fornitore prima di scrivere il codice.
• Postman e Insomnia: testano API REST e simulano chiamate webhook. Postman ha mock server integrati.
• Stripe CLI: forward dei webhook Stripe verso il tuo localhost con replay degli eventi storici.

Produzione: orchestrazione e reliability

• Hookdeck (lanciato 2020): proxy webhook con coda, retry, dashboard, replay. Riduce la pressione di affidabilità sul tuo endpoint.
• Pipedream: piattaforma serverless per workflow webhook-driven in JavaScript/Python. 500+ integrazioni.
• n8n self-hosted: alternativa open source a Zapier. Lo installi su Docker, ottieni un orchestratore visuale senza pagare per esecuzione.
• Zapier e Integromat (rebrand a Make solo nel 2022): low-code dominanti con 3000+ app connesse.

Code e processing asincrono

• RabbitMQ: broker AMQP self-hosted o managed. Code, exchange, routing, DLQ.
• AWS SQS + SNS: code FIFO/standard managed, integrate con Lambda. Standard per AWS cloud-native.
• GCP Pub/Sub: equivalente Google con push subscription verso endpoint HTTPS. Buono su Cloud Run.
• Azure Event Grid: il servizio Microsoft per eventi e webhook su Azure.

Endpoint nativi più usati

• Stripe webhooks: il gold standard per documentazione, retry, signing, CLI di test. Se devi imparare un buon sistema webhook, studia Stripe.
• GitHub webhooks: per CI/CD e automation. Documentazione chiara, firma HMAC SHA-256 dal 2019.
• Shopify webhooks: indispensabili per e-commerce. Eventi su ordini, prodotti, carrelli abbandonati, customer.
• WooCommerce webhooks REST API: nativi nel core di WooCommerce, configurabili dall’admin WordPress.

Errori comuni nelle integrazioni webhook

Idempotency mancante

L’errore numero uno: il dev assume che un webhook arrivi una volta sola e non implementa la deduplica. Risultato: doppi ordini, doppi pagamenti, doppie fatture la prima volta che Stripe riprova (succede settimanalmente). Implementa sempre la tabella processed_events.

Timeout troppo bassi

Stripe aspetta 30 secondi prima di considerare un webhook fallito. Se il tuo endpoint processa l’evento in modo sincrono (write DB, API esterne, mail) e impiega 35 secondi, Stripe ti riprova e finisci in loop con duplicati. Regola: rispondi 200 entro 1 secondo, processa in coda asincrona.

Nessuna DLQ, nessun monitoring

L’evento fallisce N volte, muore. Nessuno se ne accorge. Sei mesi dopo scopri che mancano 400 ordini perché un type di evento crashava il parser. Una DLQ con alerting Prometheus/Datadog ti avvisa entro un’ora.

Signing key committata su Git

Classico. Usa variabili d’ambiente, vault, secret manager (AWS Secrets Manager, HashiCorp Vault). Mai in chiaro.

Parsing JSON prima della validazione firma

Bug subdolo: deserializzi il body, ricalcoli la firma sul body riserializzato, firma diversa perché pretty-printing o ordine chiavi cambiano. Calcola la firma sul body raw ricevuto, poi parse-a il JSON. In molti framework devi configurare esplicitamente parser raw per gli endpoint webhook.

Caso reale: PMI italiana, Shopify → Odoo da polling a webhook

Cliente settore arredamento — fatturato ~3.5M€, 4 sedi tra Veneto e Lombardia — 60-90 ordini al giorno su Shopify Plus da riconciliare nel loro ERP Odoo per fatturazione, magazzino, planning produzione.

Situazione iniziale

Sviluppo originale del 2019 faceva polling su Shopify ogni 5 minuti. Job che interrogava GET /admin/api/2021-04/orders.json?updated_at_min=... e sincronizzava in Odoo via XML-RPC. Tre problemi:

• Latenza media 150 secondi: i clienti che chiamavano per chiedere lo stato dell’ordine subito dopo l’acquisto si sentivano dire “non lo vediamo ancora”.
• Rate limit saturo: 288 chiamate/giorno solo per ordini, più altri 4 job (prodotti, varianti, clienti, inventory). Errori 429 alle 11 del mattino.
• Eventi persi su modifiche: ordini cambiati e ri-cambiati nello stesso intervallo perdevano stati intermedi (partial refund seguito da fulfillment).

La migrazione

Pattern hybrid implementato in 7 settimane. Webhook Shopify per orders/create, orders/updated, orders/paid, orders/fulfilled, orders/cancelled, refunds/create. Endpoint Python su server pubblico esposto via Cloudflare, validazione firma HMAC SHA-256, scrittura su coda RabbitMQ, worker che sincronizza in Odoo via XML-RPC con idempotency su X-Shopify-Webhook-Id. In parallelo, vecchio polling ridotto a job notturno alle 03:00 che recupera gli ordini delle ultime 24 ore e fa diff con Odoo. DLQ monitorata via Grafana con alert Telegram.

Risultati a 90 giorni

• Latenza media da 150 secondi a 900 ms (-99.4%).
• Chiamate API a Shopify da 288/giorno a 8 (-97%).
• Discrepanze in riconciliazione: 0.3% nei primi 30 giorni, 0.05% dopo 60 giorni di tuning.
• Ticket “non vedo il mio ordine”: -82% nel primo mese.

Roadmap di 60 giorni per migrare da polling a webhook

Per chi parte da polling e vuole passare a webhook senza interrompere la produzione, ecco la roadmap che usiamo nei progetti reali.

Settimane 1-2: assessment e design

Inventario integrazioni esistenti: lista endpoint polling-ati, frequenza, volume eventi/giorno, criticità. Per ognuna verifica se il fornitore supporta webhook. Documenta eventi necessari e payload attesi. Scegli l’architettura di processing: coda (RabbitMQ, SQS), worker, persistenza idempotency. Decidi dove esporre l’endpoint (server proprio, reverse proxy, Hookdeck).

Settimane 3-4: implementazione endpoint e validazione

Scrivi l’endpoint HTTPS con validazione firma HMAC SHA-256, dedup su event_id, scrittura su coda. Testa con ngrok in locale e Webhook.site per il debug. Unit test sulla funzione di validazione firma. Deploy in staging.

Settimane 5-6: shadow mode

Webhook attivi in produzione, polling non disattivato. Per due settimane girano entrambi in parallelo: il webhook scrive su tabella separata, il polling continua sul flusso principale. Confronta i dati: ogni evento visto dal webhook deve essere visto dal polling, e viceversa. Le discrepanze ti dicono dove correggere.

Settimane 7-8: cutover e backoff polling

Switch del flusso principale ai webhook. Il polling passa da “ogni 5 minuti” a “ogni 6 ore” come riconciliazione. Monitora le discrepanze tra le due fonti: deve essere <0.5%. Configura alerting su DLQ, su rate di errore endpoint, su gap di event_id consecutivi. Go-live, retrospettiva a 30 giorni.

Domande frequenti

Quanto costa migrare da polling a webhook per una PMI italiana?

Una migrazione completa per una singola integrazione media (es. Shopify → ERP) costa tipicamente tra 4000 e 9000 euro tutto incluso: assessment, sviluppo endpoint, queue, testing shadow, monitoring. Il ROI si misura in mesi quando l’integrazione è critica — il caso reale sopra ha ammortizzato il costo in 3 mesi solo per ticket di supporto risparmiati.

Posso usare un orchestratore (Zapier/n8n) invece di scrivere codice?

Sì, per flussi semplici sotto i 10.000 eventi/mese le piattaforme low-code sono ottime. Zapier costa di più ma è più semplice, n8n self-hosted è gratis ma richiede DevOps, Pipedream è una via di mezzo. Per volumi alti o logiche complesse (transazioni multi-step, retry custom, idempotency cross-evento) conviene codice custom.

Cosa succede se il mio endpoint webhook va down per un’ora?

Dipende dal fornitore. Stripe riprova per 3 giorni con backoff esponenziale, Shopify per 48 ore con 19 tentativi, GitHub per 8 ore. Un downtime di 1 ora non fa perdere eventi se il fornitore implementa retry. Combinandolo con il pattern hybrid (polling notturno di riconciliazione) la perdita è zero anche con downtime più lunghi.

Webhook funzionano dietro firewall corporate?

Non senza esporre un endpoint pubblico. Le opzioni: aprire porta inbound (sconsigliato), reverse proxy in DMZ (es. nginx) che inoltra al backend interno, oppure servizio tipo Hookdeck con connessione persistente in uscita.

Devo cifrare il payload webhook oltre alla firma?

Se trasporti dati sensibili (GDPR, dati di pagamento PCI), sì. L’HTTPS cripta il trasporto, la firma HMAC garantisce autenticità non confidenzialità. Per payload PCI o sanitari valuta JWE (JWT cifrato) o encryption applicativa del body. La maggior parte dei provider mainstream non offre payload cifrati nativi.

Quanto deve essere veloce il mio endpoint webhook?

Regola pratica: rispondi 200 al fornitore entro 1 secondo, idealmente sotto i 200 ms. Tutto il lavoro pesante (DB write, API esterne, mail) va in coda asincrona.

Posso testare webhook senza un fornitore reale?

Sì. Stripe CLI genera eventi finti con firma valida. GitHub permette rilanci manuali dall’admin del repo. Per test generici scrivi uno script Python o curl che POST-a payload di esempio con firma HMAC calcolata dal tuo secret di test. Postman ha collection di esempio per Stripe, Shopify, GitHub.