Webhook e notifiche verso sistemi esterni

Il firebase push connector di magnews può inviare notifiche e dati verso sistemi esterni (CRM, piattaforme di analytics, data warehouse, o sistemi proprietari) tramite webhook HTTP.
I webhook consentono di ricevere in tempo reale informazioni sugli eventi generati dalle notifiche push — come consegne, aperture, click e conversioni — permettendo l’integrazione diretta con altri ecosistemi informativi.

1. Cos’è un webhook

Un webhook è un endpoint HTTP esposto da un sistema esterno, che riceve una chiamata automatica da magnews ogni volta che si verifica un determinato evento.
Nel caso del firebase connector, i webhook vengono usati per inviare le informazioni di tracking push (delivery, open, click, conversion) e sincronizzare i dati utente con sistemi di terze parti.

2. Configurare il webhook in magnews

Passaggi principali

1. Vai in Management → AppCenter → Google Firebase Push Connector.

2. Apri la sezione Webhook Configuration.

3. Inserisci l’URL del servizio esterno che riceverà i dati (es. https://api.example.com/magnews-push-events).

4. Seleziona il tipo di eventi da notificare (es. delivery, click, open, conversion).

5. (Opzionale) imposta le credenziali di autenticazione.

6. Salva la configurazione.

Nota: se non viene impostato alcun URL, il webhook non viene attivato e magnews non effettua invii esterni.
Gli eventi vengono comunque tracciati internamente nei log e nei report di piattaforma.

3. Autenticazione e sicurezza

Ogni chiamata inviata dal webhook può includere un header di autenticazione personalizzato, utile per proteggere l’endpoint ricevente.

Esempio di header HTTP:

Authorization: Bearer <token_personalizzato>
Content-Type: application/json

Puoi configurare il valore dell’header direttamente nella sezione di setup del webhook in AppCenter.

Attenzione: assicurati che il sistema ricevente validi correttamente il token per evitare accessi non autorizzati o spoofing.
Il connettore non gestisce il rinnovo automatico dei token: se il valore scade, deve essere aggiornato manualmente.

4. Struttura del DTO inviato dal connettore

Ogni volta che un evento push viene registrato, magnews invia al webhook un JSON (DTO) con struttura coerente e campi chiave ben definiti.

Esempio di payload completo

{
  "contact": {
    "id": 3,
    "email": "mario.rossi@example.com",
    "database_id": 1
  },
  "message": {
    "mn_message_id": "mnid2m.1234.12.12.1.2",
    "app_id": "app-android",
    "title": "Benvenuto!",
    "body": "Scopri le novità nel tuo profilo.",
    "payload": {
      "pushdata.url": "https://example.com/profile"
    }
  },
  "delivery": {
    "status": "CLICK",
    "event_time": "2025-10-30T09:45:10Z",
    "push_token": "token123",
    "platform": "android"
  },
  "timestamp": "2025-10-30T09:45:12Z"
}

Campi principali

Nota tecnica: il campo mn_message_id consente di correlare i dati webhook con quelli interni a magnews, garantendo la riconciliazione tra sistemi.

5. Tipologie di eventi supportati

Il webhook può essere configurato per ricevere uno o più dei seguenti eventi:

• DELIVERED → notifica inviata con successo a Firebase;

• OPEN → notifica aperta dall’utente;

• CLICK → utente ha interagito con la notifica;

• CONVERT → azione di conversione collegata al messaggio;

• DISMISS → notifica chiusa o ignorata;

• ERROR → errore di consegna o token non valido.

Ogni evento è inviato come payload JSON autonomo, indipendente dagli altri.

6. Casi d’uso tipici

1. Integrazione CRM

Ricevi in tempo reale le interazioni push degli utenti per aggiornare i profili nel tuo CRM (es. Salesforce, HubSpot, Dynamics).

2. Data Warehouse o Analytics

Invia gli eventi push a un sistema di analytics per calcolare tassi di apertura e conversione integrati con altri canali.

3. Sistemi proprietari

Ricevi le notifiche per eseguire azioni automatiche (es. assegnare badge, aggiornare punteggi fedeltà, inviare messaggi in-app).

Suggerimento: utilizza code di ricezione (es. RabbitMQ, Kafka, Pub/Sub) per gestire in modo scalabile flussi ad alto volume di webhook.

7. Troubleshooting e raccomandazioni

• Se il sistema ricevente risponde con codici HTTP 4xx o 5xx, magnews considera la consegna fallita ma non effettua retry automatici.

• Implementa una coda intermedia nel tuo endpoint per evitare perdita di eventi in caso di downtime temporanei.

• Usa log applicativi per confrontare mn_message_id con il corrispondente record interno di tracking.

• Testa l’invio manuale dal pannello AppCenter per verificare che l’URL e l’autenticazione siano configurati correttamente.