Come si usano i webhook in magnews

I webhook sono un meccanismo che permette a magnews di inviare notifiche automatiche verso sistemi esterni quando si verifica un determinato evento (ad esempio la creazione di un contatto o l’apertura di un’email).

In questa pagina trovi la documentazione tecnica per implementarli. Se invece vuoi capire quando e perché usarli dal punto di vista funzionale, consulta l’articolo dedicato ai casi d’uso e agli scenari di integrazione.

Eventi supportati (topic)

I webhook funzionano tramite eventi, chiamati topic.
Ogni topic rappresenta un’azione o un cambiamento che avviene all’interno di magnews e che può generare una notifica verso un sistema esterno.

Quando crei una sottoscrizione webhook, scegli quali topic ascoltare, in base alle informazioni che ti servono.

Di seguito trovi i topic disponibili, raggruppati per area funzionale.

Guida tecnica alla sottoscrizione

La gestione delle sottoscrizioni webhook avviene tramite una risorsa REST dedicata. Una sottoscrizione definisce dove magnews deve inviare le notifiche (endpoint) e quali eventi deve inoltrare (topic).

Creazione di una sottoscrizione

Per attivare un webhook, invia una richiesta POST all’endpoint /webhooks/create specificando:

• uri
  L’URL del tuo endpoint che riceverà le notifiche (es. https://tuo-sistema.com/webhook-receiver).
• topics
  Una stringa separata da virgole contenente i topic desiderati (es. contacts/create,contacts/update).

Per vedere un esempio completo della richiesta api per la sottoscrizione, consulta la nostra documentazione sull'API rest.

Verifica dell'URL

Al momento della creazione, magnews esegue una verifica dell’URL fornito per accertarsi che l’endpoint sia raggiungibile e che risponda correttamente.

1. magnews invia una richiesta POST all'url fornito con body JSON {"verify": true}.
2. La richiesta include l’header X-magnews-hmacsha256 (vedi sezione "Verifica della firma").
3. Il tuo sistema deve validare la firma e rispondere con 200 OK.

Se la verifica non va a buon fine, la sottoscrizione non viene creata e l’endpoint restituisce un errore. La creazione può fallire anche se è stato raggiunto il limite massimo di sottoscrizioni per account.

Aggiornamento ed eliminazione di una sottoscrizione

Una volta creata, puoi gestire una sottoscrizione tramite:

• POST /webhooks/update
  Aggiorna una sottoscrizione esistente. È richiesto l’id; uri, topics e status sono opzionali.
• DELETE /webhooks/delete/{id}
  Elimina una sottoscrizione. Restituisce 200 se l’operazione va a buon fine e 404 se la sottoscrizione non esiste.

Gestione degli eventi e sicurezza

Tutte le notifiche webhook inviate da magnews sono richieste POST con corpo in formato JSON. L’endpoint ricevente deve rispondere con 200 OK per confermare la ricezione: qualsiasi altro codice di stato viene considerato un errore e l'evento verrà inviato nuovamente (per maggiori dettagli consulta la sezione "Gestione errori, retry e backoff").

Header HTTP

Ogni notifica include i seguenti header tecnici:

• X-magnews-webhook-topic: topic che ha scatenato l’evento (es. contacts/update).
• X-magnews-webhook-subscriptionid: ID univoco della sottoscrizione.
• X-magnews-webhook-event-timestamp: timestamp dell’evento in formato ISO 8601 (UTC).
• X-magnews-hmacsha256: firma di sicurezza del payload.

Verifica della firma (HMAC-SHA256)

Per garantire che la richiesta provenga effettivamente da magnews, verifica la firma HMAC-SHA256 presente nell’header X-magnews-hmacsha256. La firma viene calcolata a partire dal corpo grezzo della richiesta e dal client_secret associato al Certificato Digitale associato alla tua applicazione.

1. Recupera il raw body della richiesta (senza trasformazioni o parsing).
2. Calcola l’HMAC-SHA256 del body usando il client_secret come chiave.
3. Confronta l’hash ottenuto con il valore di X-magnews-hmacsha256.

Se i due valori coincidono, la richiesta può essere considerata autentica.

Requisiti HTTPS

L’endpoint deve essere esposto in HTTPS e presentare un certificato valido (non auto-firmato).

Tempistiche di invio degli eventi

L’invio degli eventi tramite webhook avviene in near real-time. Questo significa che l’evento non viene necessariamente consegnato nell’esatto istante in cui si verifica all’interno della piattaforma.

In condizioni normali, la notifica viene inviata entro pochi secondi, ma può verificarsi un ritardo di alcuni minuti dall’evento originale, in particolare in presenza di code di elaborazione o carichi elevati.

Per questo motivo, le integrazioni devono considerare i webhook come eventualmente consistenti e non come notifiche sincrone.

Gestione errori, retry e backoff

Ogni sottoscrizione mantiene un proprio avanzamento sugli eventi. In caso di errori, magnews applica una logica di retry con backoff progressivo per evitare tentativi troppo ravvicinati verso endpoint non raggiungibili.

Se gli errori consecutivi superano determinate soglie, la sottoscrizione può essere sospesa automaticamente per evitare un utilizzo inefficiente delle risorse. In questo caso, dopo aver risolto il problema sull’endpoint, sarà necessario riattivare manualmente il webhook (sempre tramite chiamata API).

Monitoraggio

È disponibile una vista di monitoraggio in: Monitor > Sviluppo > Webhook, pensata per un controllo rapido dello stato delle sottoscrizioni.

La schermata mostra le informazioni principali di ogni webhook, tra cui:

• endpoint (URI)
• topic sottoscritti
• ultima esecuzione
• eventuale backoff attivo
• stato della sottoscrizione (attiva o sospesa)

Se il sistema rileva errori consecutivi nell’invio degli eventi verso l’endpoint, vengono attivate automaticamente notifiche di sistema:

• Avviso di malfunzionamento: inviato quando viene superata una soglia di errori consecutivi, per segnalare possibili problemi di raggiungibilità o risposta dell’endpoint.
• Notifica di sospensione: inviata quando, a causa del persistere degli errori, la sottoscrizione viene sospesa automaticamente.

Le notifiche vengono inviate agli indirizzi email associati ai contatti principali dell’account (ad esempio il contatto commerciale e il contatto cliente). Non è prevista una configurazione manuale degli indirizzi destinatari.

In caso di sospensione, dopo aver risolto il problema tecnico sull’endpoint esterno, sarà necessario riattivare manualmente la sottoscrizione.