Cosa sono i webhook
I webhook sono notifiche HTTP automatiche che Newsletter G Tech Group invia a un'URL esterno (endpoint) quando si verificano eventi specifici nella piattaforma. Permettono di integrare la piattaforma in tempo reale con CRM, CMS, gestionali, data warehouse, sistemi di e-commerce e tool analytics senza polling continuo (richieste API ripetute) che sarebbe inefficiente e rate-limitato. Sono il meccanismo push standard delle moderne API event-driven.
Eventi disponibili
I webhook in Newsletter G Tech Group coprono i principali eventi del ciclo email: subscriber.created (nuovo contatto aggiunto), subscriber.confirmed (double opt-in completato), subscriber.unsubscribed (cancellazione), campaign.sent (campagna inviata con successo), campaign.opened (apertura tracciata), campaign.clicked (clic su link), campaign.bounced (bounce rilevato), campaign.complained (spam complaint), list.imported (import lista completato), tag.added, tag.removed, custom_field.updated.
Configurazione webhook
Dal menu integrazioni clicca aggiungi webhook. Inserisci URL endpoint del tuo sistema (deve essere HTTPS, no HTTP), scegli gli eventi da iscrivere (puoi sottoscriverne uno specifico o tutti), definisci il formato payload (JSON e' standard, alcuni endpoint legacy richiedono XML), configura un secret token per la firma HMAC che garantisce autenticita' della richiesta.
Firma HMAC
Ogni webhook include un'header HTTP X-Signature con firma HMAC-SHA256 del payload, calcolata con il secret token che hai configurato. Il sistema ricevente deve verificare la firma calcolando l'HMAC-SHA256 del body con lo stesso secret e confrontandolo con l'header. Così' autentica che la richiesta arrivi davvero da Newsletter G Tech Group e non sia un'attacco di un terzo che conosce l'endpoint. Senza firma HMAC valida, scarta la richiesta.
Formato payload
Il payload JSON tipico contiene: event_type (es. subscriber.confirmed), timestamp ISO 8601 con timezone (es. 2026-01-15T10:30:00+01:00), data oggetto evento con tutti i campi rilevanti (email, list_id, campaign_id, custom_fields), metadata account (account_id, environment production/staging). Esempio: {"event":"subscriber.confirmed","timestamp":"2026-01-15T10:30:00+01:00","data":{"email":"mario@example.com","list_id":42,"first_name":"Mario"}}.
Retry automatico
Se l'endpoint risponde con errore (codici 5xx o timeout oltre 5 secondi), Newsletter G Tech Group ritenta automaticamente con backoff esponenziale: 1 minuto, 5 minuti, 30 minuti, 2 ore, 12 ore. Dopo 24 ore di fallimenti consecutivi, il webhook viene disabilitato e ricevi notifica email all'amministratore per intervenire manualmente. Così' eventi importanti non vengono persi per blip temporanei dell'endpoint.
Validazione endpoint
L'endpoint ricevente deve rispondere entro 5 secondi con codice HTTP 200, 201 o 204. Risposte più' lente triggera retry (potenzialmente duplicati). Per elaborazioni pesanti (es. salvataggio su DB con join multipli), accoda il payload in una queue interna (Redis, RabbitMQ) e elabora in background asincrono, restituendo subito 200 al webhook. Pattern enqueue-and-respond e' lo standard.
Casi d'uso integrazione CRM
Webhook subscriber.confirmed crea automaticamente un contatto nel CRM con sorgente newsletter e tag automatico newsletter_subscriber. Webhook campaign.clicked su link demo aggiorna lead scoring del CRM (+10 punti). Webhook campaign.opened multiplo triggera task del commerciale dopo 3 aperture consecutive (lead caldo).
Casi d'uso analytics
Webhook su tutti gli eventi popola un data warehouse interno (BigQuery, Snowflake, Redshift) per analisi avanzate cross-platform. Combini dati email con dati e-commerce, dati prodotto, dati CRM per attribution modeling sofisticato e dashboard executive complete.
Test webhook
La piattaforma permette test manuale dal pannello: invia un payload di esempio all'endpoint configurato e mostra risposta ricevuta (status code, body, header). Utile durante setup per verificare configurazione, firma HMAC e parsing del payload prima di andare in produzione. Webhook.site e' anche utile come endpoint di debug temporaneo.
Sicurezza
Whitelist gli IP di origine se conosciuti, valida sempre HMAC, log ogni webhook ricevuto per audit.
Idempotenza
Implementa endpoint webhook idempotenti: ricevere lo stesso evento 2 volte (per retry) non deve causare doppia elaborazione. Usa event_id univoco come chiave di deduplicazione nel DB ricevente.
Webhook vs polling API
Webhook (push) vince su polling API (pull) per latency e efficienza: con webhook scopri eventi in secondi, con polling devi chiamare ogni X minuti e perdere gli eventi tra le chiamate. Usa webhook quando possibile.
Webhook batch vs streaming
Newsletter G Tech Group invia webhook 1-by-1 di default (real-time). Per volumi alti (10k+ eventi al minuto), modalita' batch (aggregati ogni N secondi) riduce carico endpoint riducendo numero richieste.
Backpressure
Se l'endpoint e' lento o sovraccarico, retry esponenziale evita di sovraccaricarlo. In casi estremi, considera circuit breaker pattern: dopo X fallimenti, sospendi webhook per Y minuti.
Logging
Log ogni webhook ricevuto con timestamp, payload, response time, status. Util per debug e SLA monitoring. Conserva almeno 30 giorni di log per analisi storica.
Sicurezza endpoint
Endpoint webhook deve essere protetto: HTTPS obbligatorio, validazione HMAC, IP whitelist se possibile, rate limit sul ricevitore per prevenire abuse. Endpoint pubblico non sicuro = vulnerabilita'.
Test in CI
Include test webhook in pipeline CI/CD: ogni deploy verifica che endpoint webhook risponda correttamente con payload sample.
Filtraggio eventi
Configura filtri per ridurre rumore: ricevi solo eventi specifici di interesse (es. solo subscriber.created e campaign.clicked, ignorando aperture). Riduce carico e rumore nel sistema ricevente.
Versionamento payload
Payload schema puo' evolvere. Versioning del payload (v1, v2) permette migrazione graduale senza rompere integrazioni esistenti.
Testing locale
Per testare webhook in development, usa ngrok per esporre localhost: Newsletter G Tech Group invia webhook al tuo URL ngrok, codice locale lo riceve e debugga.
Hai bisogno di aiuto?
Se vuoi usare Newsletter G Tech Group, scrivici tramite il modulo di contatto.