Come creare webhook affidabili di Microsoft Graph per SharePoint e Microsoft 365

By Mirko Peters · 2025-11-16

Crea webhook affidabili di Microsoft Graph per SharePoint e Microsoft 365 con validazione sicura, rinnovi automatizzati e consegna robusta delle notifiche.

Automatically translated with AI from the original post. Read the English original

Creare webhook affidabili di Microsoft Graph per SharePoint e Microsoft 365 può mettere alla prova anche gli sviluppatori più esperti. Potresti riscontrare problemi come un errore di validazione se il tuo endpoint non restituisce il token di validazione o non risponde con uno stato 200 OK. Tra i problemi più comuni ci sono endpoint bloccati da firewall, configurazioni di rete errate o interferenze di middleware. Retry persi e sottoscrizioni scadute si verificano spesso quando il servizio non riceve la richiesta di validazione o quando gli endpoint non sono accessibili pubblicamente. In questo articolo imparerai a evitare questi problemi e a creare una pipeline di notifiche robusta e sicura, con una checklist pratica e le migliori pratiche.

Punti chiave

• I webhook di Microsoft Graph forniscono notifiche in tempo reale sulle modifiche in Microsoft 365, eliminando la necessità di un polling costante.

• Assicurati che il tuo endpoint webhook sia accessibile pubblicamente e usi HTTPS per garantire sicurezza e affidabilità.

• Rispondi rapidamente alle richieste di validazione restituendo il token di validazione, così da attivare correttamente la tua sottoscrizione webhook.

• Implementa una strategia robusta di retry e backoff per gestire i guasti nella consegna delle notifiche e prevenire la perdita di dati.

• Automatizza il rinnovo delle sottoscrizioni e monitora la tua pipeline di webhook per garantire notifiche continue e affidabili.

Fondamenti dei webhook di Microsoft Graph

Cosa sono i webhook di Microsoft Graph

Un webhook è una richiesta HTTP, attivata da un evento in un sistema di origine e inviata a un sistema di destinazione, spesso con un payload di dati. I webhook sono automatizzati: in altre parole, vengono inviati automaticamente quando il loro evento si verifica nel sistema di origine.

Usi i webhook di Microsoft Graph per ricevere notifiche in tempo reale sulle modifiche nel tuo ambiente Microsoft 365. Non devi quindi interrogare costantemente Microsoft Graph per cercare aggiornamenti: la tua applicazione riceve una notifica non appena accade qualcosa di importante. In questo modo resti aggiornato e sincronizzato con i dati accessibili tramite Microsoft Graph. Inoltre elimina la necessità di un'infrastruttura di polling, in cui invii di frequente richieste a Microsoft Graph per verificare le ultime modifiche.

Puoi configurare notifiche per molti tipi di eventi, ad esempio:

• Messaggi

• Eventi

• Contatti

• Utenti

• Gruppi

• Conversazioni

• File di OneDrive

• Avvisi

Ad esempio, potresti voler creare automaticamente un account in un sistema di terze parti per la registrazione delle ore quando un nuovo utente entra nella tua organizzazione. Potresti anche avviare l'elaborazione di contenuti, come la gestione delle note spese, quando qualcuno aggiunge un nuovo file a una libreria documenti di SharePoint o a una cartella di OneDrive.

Perché l'affidabilità è importante

I webhook di Microsoft Graph svolgono un ruolo chiave nel mantenere reattive e aggiornate le integrazioni con SharePoint e Microsoft 365. Quando la tua pipeline di webhook funziona in modo affidabile, le applicazioni reagiscono alle modifiche in tempo reale. Gli utenti vedono sempre i dati più recenti, il che migliora la loro esperienza e riduce il rischio di informazioni obsolete.

Tuttavia, i problemi di affidabilità possono causare conseguenze serie:

• I guasti dei webhook possono compromettere la funzionalità delle applicazioni se non vengono gestiti correttamente.

• Picchi improvvisi di traffico possono sovraccaricare i server, causando downtime e perdita di richieste webhook.

• Non consumare i webhook può comportare perdita e incoerenza dei dati se non esiste un meccanismo di ritrasmissione.

• Gli URL dei webhook non protetti possono essere sfruttati, permettendo agli aggressori di inviare dati corrotti.

Per costruire una soluzione robusta, dovresti combinare i webhook con le delta query per tenere traccia delle modifiche in modo efficiente. Devi inoltre predisporre processi per verificare e rinnovare regolarmente le sottoscrizioni. Per le risorse che si aggiornano spesso, raggruppare le richieste (batching) aiuta a gestire il carico.

Configurare e validare i webhook

Configurare i webhook di Microsoft Graph per SharePoint e Microsoft 365 richiede diversi passaggi importanti. Devi registrare il webhook, gestire le richieste di convalida e proteggere il tuo endpoint. Ogni passaggio è fondamentale per garantire che la pipeline delle notifiche funzioni in modo affidabile e sicuro.

Registrare i webhook di Microsoft Graph

Inizi creando una sottoscrizione webhook. Questo processo consente alla tua applicazione di ricevere notifiche sulle modifiche alle risorse di Microsoft 365. Segui questi passaggi per registrare il webhook:

1. Crea un endpoint accessibile pubblicamente che usi HTTPS. Questo endpoint riceverà le notifiche da Microsoft Graph.

2. Invia una richiesta POST all'endpoint /subscriptions di Microsoft Graph.

3. Nella richiesta di sottoscrizione specifica:

   • changeType: i tipi di modifica che vuoi monitorare, ad esempio "created", "updated" o "deleted".

   • notificationUrl: l'URL del tuo endpoint webhook.

   • resource: la risorsa che vuoi monitorare, ad esempio "/users" o "/drive/root".

   • expirationDateTime: la data e l'ora in cui la sottoscrizione deve scadere.

   • Le proprietà facoltative, come clientState, ti aiutano a verificare l'origine delle notifiche.

Esempio di richiesta di sottoscrizione:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

Devi assicurarti che il tuo endpoint sia accessibile pubblicamente e protetto con HTTPS. Microsoft Graph convalida l'URL di notifica prima di completare la sottoscrizione. Devi rinnovare le sottoscrizioni regolarmente per continuare a ricevere notifiche. Il tuo endpoint deve fornire risposte HTTP tempestive e coerenti per evitare di perdere notifiche.

Ecco un riepilogo dei campi obbligatori per la registrazione:

Gestire le richieste di convalida

Dopo aver registrato il webhook, Microsoft Graph invia una richiesta di convalida al tuo endpoint. Devi rispondere correttamente per completare il processo di sottoscrizione. Quando il tuo endpoint riceve una richiesta GET con il parametro di query validationToken, devi restituire questo token nel corpo della risposta come testo normale e rispondere con lo stato 200 OK.

• Se non restituisci il validationToken, si verifica un errore di convalida. Questo significa che Microsoft Graph non può confermare il tuo endpoint e non riceverai notifiche.

• Dovresti usare la proprietà clientState per verificare che le richieste provengano dalla tua sottoscrizione.

• Restituisci sempre il validationToken nel corpo della risposta come testo normale entro 10 secondi.

💡 Suggerimento: rispondere in modo rapido e accurato alle richieste di convalida garantisce che la sottoscrizione al webhook si attivi senza problemi.

HTTPS e sicurezza dell'endpoint

Proteggere l'endpoint del webhook è essenziale. I webhook di Microsoft Graph richiedono la crittografia HTTPS per proteggere i dati sensibili durante la comunicazione. Dovresti verificare le richieste in arrivo controllando la firma creata con una chiave segreta condivisa. Usa percorsi complessi e generati casualmente per i tuoi URL di callback, così da renderli più difficili da indovinare.

• Aggiungi un elenco di indirizzi IP consentiti (IP whitelisting) per gli endpoint dell'API di Microsoft Graph.

• Includi i token di autenticazione negli header delle richieste.

• Monitora l'utilizzo delle API per individuare schemi insoliti o picchi di attività.

• Limita l'accesso alle API di Microsoft Graph e Outlook. Solo il personale autorizzato dovrebbe avere accesso e dovresti imporre l'autenticazione a più fattori (MFA).

• Implementa soluzioni avanzate di sicurezza per gli endpoint che usano analisi comportamentale e machine learning per identificare le minacce.

• Esegui regolarmente audit di sicurezza per individuare e correggere le vulnerabilità.

Ogni callback del webhook usa un JSON Web Token (JWT) firmato nell'intestazione Authentication della richiesta HTTPS in ingresso. Puoi applicare le tecniche standard di validazione dei JWT di OpenID Connect per garantire l'integrità del token.

Devi usare HTTPS per tutti gli endpoint dei webhook. Questo requisito protegge i tuoi dati e garantisce la conformità agli standard di sicurezza di Microsoft. Proteggere l'endpoint aiuta a prevenire accessi non autorizzati e attacchi.

Seguendo questi passaggi, configuri una pipeline affidabile e sicura di Microsoft Graph Webhooks per SharePoint e Microsoft 365. Così la tua applicazione riceve le notifiche in modo tempestivo e sicuro.

Elaborazione e protezione delle notifiche

Dopo aver configurato l'endpoint del webhook, devi elaborare le notifiche in arrivo in modo sicuro e affidabile. Questo passaggio garantisce che la tua applicazione accetti solo richieste valide e che non perda mai aggiornamenti importanti da Microsoft Graph Webhooks.

Autenticazione e verifica dei token JWT

Ogni notifica di Microsoft Graph include un JSON Web Token (JWT) nell'intestazione Authorization. Devi verificare questo token prima di elaborare qualsiasi payload. Una corretta validazione del JWT protegge il sistema da richieste non autorizzate o manomesse.

Segui questi passaggi per autenticare e verificare i token JWT:

1. Controlla che il token non sia scaduto. I token includono un orario di scadenza e devi rifiutare qualsiasi token oltre tale orario.

2. Verifica che il token sia stato emesso dalla piattaforma di identità Microsoft. Convalida la firma del token per assicurarti che non sia stato alterato.

3. Assicurati che il claim "audience" del token corrisponda all'ID della tua applicazione. Questo passaggio conferma che il token era destinato alla tua app.

4. Verifica che la proprietà azp (authorized party) corrisponda al valore previsto per la tua applicazione.

Suggerimento: usa sempre librerie affidabili per la validazione dei JWT. Queste librerie ti aiutano a evitare errori comuni e mantengono sicura la tua applicazione.

Quando gestisci i token JWT, dovresti inoltre prestare attenzione alle vulnerabilità di sicurezza più comuni:

• Non verificare la firma del JWT può consentire agli aggressori di modificare il contenuto del token senza essere rilevati.

• Usare l'algoritmo 'none' nell'elaborazione dei JWT consente agli aggressori di aggirare i controlli sulla firma.

• Segreti di firma deboli facilitano agli aggressori la falsificazione di token validi.

• Gli aggressori possono inserire parametri specifici nell'intestazione JOSE per manipolare il modo in cui il sistema elabora i JWT.

Seguendo questi passaggi e precauzioni, fai in modo che solo le notifiche legittime raggiungano la tua applicazione.

Gestione dei payload delle notifiche

Dopo aver autenticato la notifica, devi elaborare il payload in modo sicuro. I payload delle notifiche contengono informazioni sull'evento che ha attivato il webhook. Per mantenere l'integrità dei dati e prevenire problemi di sicurezza, dovresti:

• Verificare che tutti i campi obbligatori siano presenti nel payload. I campi mancanti possono causare errori o un'elaborazione incompleta.

• Sanifica tutti i campi di testo prima di visualizzarli o memorizzarli nel database. Questo passaggio previene attacchi di tipo injection e danneggiamento dei dati.

• Usa la validazione dello schema per confermare che il payload corrisponda alla struttura prevista. La validazione dello schema ti aiuta a individuare modifiche impreviste o dati malformati.

• Prepara il codice a possibili cambiamenti di versione dell'API. Un parsing flessibile garantisce che la tua applicazione continui a funzionare anche se Microsoft aggiorna il formato del payload.

Nota: validare e sanificare i payload protegge il sistema da dati malformati e minacce alla sicurezza.

Implementare la logica di retry e backoff

Problemi di rete o interruzioni temporanee possono far fallire la consegna delle notifiche. Per evitare perdite di dati, ti serve una strategia di retry e backoff solida. Microsoft consiglia di usare il backoff esponenziale e code strutturate per gestire i tentativi.

Ecco una tabella che riassume i meccanismi comuni di retry e backoff:

Se non implementi una logica adeguata di ripetizione e backoff, la tua applicazione rischia di perdere notifiche o di generare incoerenze nei dati. Richieste non riuscite o limitazioni di frequenza possono impedirti di ricevere aggiornamenti critici. Il backoff esponenziale ti aiuta a gestire le richieste soggette a throttling e riduce il rischio di sovraccaricare il sistema o Microsoft Graph Webhooks.

🛡️ Best practice: tieni sempre traccia dei tentativi di ripetizione e sposta i messaggi non riusciti in una coda di abbandono dopo diversi tentativi. Questo approccio ti permette di analizzare e risolvere i problemi persistenti senza perdere dati.

Autenticando i token JWT, convalidando i payload e implementando una logica di ripetizione affidabile, crei una pipeline di notifiche sicura e resiliente. Questi passaggi ti permettono di elaborare ogni notifica da Microsoft Graph Webhooks in modo sicuro ed efficiente.

Gestione delle sottoscrizioni e del change tracking

Automatizzare il rinnovo delle sottoscrizioni

Devi mantenere attive le sottoscrizioni webhook per non perdere notifiche. Le sottoscrizioni di Microsoft Graph scadono dopo un periodo prestabilito. Se non le rinnovi, la tua applicazione smette di ricevere aggiornamenti. Puoi automatizzare il rinnovo con diversi metodi:

• Invia richieste HTTP PATCH per aggiornare la data di scadenza di ciascuna sottoscrizione.

• Pianifica l'esecuzione di queste richieste PATCH ogni giorno. In questo modo le sottoscrizioni restano valide ed eviti scadenze impreviste.

• Tieni traccia della data e ora di scadenza di ogni sottoscrizione. Rinnova qualsiasi sottoscrizione che sta per scadere.

• Se una sottoscrizione scade, creane subito una nuova per ripristinare il flusso di notifiche.

Suggerimento: automatizzare i rinnovi riduce il lavoro manuale e garantisce che il sistema resti collegato a Microsoft Graph.

Monitoraggio e avvisi

Devi monitorare lo stato della pipeline dei webhook. Configura avvisi che ti segnalino se una sottoscrizione non viene rinnovata o se l'endpoint smette di rispondere. Usa la registrazione dei log per tracciare le notifiche in arrivo e i tentativi di rinnovo. Questo ti aiuta a individuare i problemi prima che abbiano un impatto sugli utenti.

• Monitora lo stato e le date di scadenza delle sottoscrizioni.

• Configura avvisi per i rinnovi non riusciti o le notifiche mancate.

• Registra nei log tutti gli eventi webhook e gli errori per la risoluzione dei problemi.

🛎️ Il monitoraggio proattivo ti aiuta a risolvere rapidamente i problemi e mantiene l'integrazione affidabile.

Uso delle query delta per il change tracking

Le query delta ti aiutano a tracciare le modifiche in SharePoint e nelle risorse di Microsoft 365 in modo efficiente. Puoi usarle per ricevere solo i dati nuovi o aggiornati, il che riduce la necessità di polling frequenti e abbassa il rischio di throttling.

• Le query delta permettono alla tua applicazione di tracciare le modifiche senza scaricare tutti i dati ogni volta.

• Funzionano bene con SharePoint e Microsoft 365, inviando notifiche solo quando qualcosa cambia.

• Usando le query delta risparmi larghezza di banda e migliori le prestazioni.

Tuttavia, le query delta presentano alcune limitazioni:

Nota: testa sempre l'implementazione delle query delta per gestire queste limitazioni e garantire un change tracking accurato.

Automatizzando i rinnovi, monitorando la pipeline e usando le query delta, costruisci un sistema webhook affidabile ed efficiente per SharePoint e Microsoft 365.

Puoi creare webhook di Microsoft Graph affidabili seguendo un processo chiaro. Inizia creando le sottoscrizioni e usando le delta query per tenere traccia delle modifiche. Automatizza i rinnovi e monitora la pipeline alla ricerca di problemi. Dai priorità a validazione, sicurezza e resilienza in ogni fase. Per verificare che sia pronto per la produzione, consulta questa checklist:

• Mantieni la documentazione aggiornata e tieni informati i team di supporto.

• Pianifica controlli regolari sullo stato delle sottoscrizioni.

• Usa scansioni di sicurezza nella pipeline CI e mantieni i log di audit.

Applica queste best practice per garantire che le tue integrazioni con SharePoint e Microsoft 365 restino affidabili.

Domande frequenti

Come si rinnova una sottoscrizione webhook di Microsoft Graph scaduta?

Invia una richiesta PATCH all'endpoint /subscriptions/{id} di Microsoft Graph. Aggiorna il campo expirationDateTime. Pianifica l'esecuzione di questo processo ogni giorno. In questo modo le sottoscrizioni restano attive e non perdi notifiche.

Cosa fare se il tuo endpoint webhook non supera la validazione?

Verifica che l'endpoint restituisca il validationToken come testo semplice nel corpo della risposta. Rispondi con lo stato 200 OK. Assicurati che l'endpoint sia accessibile pubblicamente e usi HTTPS.

Come si protegge un endpoint webhook?

Usa HTTPS per tutti gli endpoint. Valida i token JWT in ogni richiesta. Limita l'accesso con autenticazione e whitelist di indirizzi IP. Monitora attività insolite. Verifica regolarmente le impostazioni di sicurezza.

Perché usare le delta query con i webhook?

Le delta query ti permettono di tenere traccia solo dei dati nuovi o modificati. Questo riduce il consumo di banda e migliora le prestazioni. Non scarichi tutti i dati ogni volta, rendendo l'integrazione più rapida ed efficiente.

Qual è il modo migliore per gestire le notifiche webhook non riuscite?

Implementa una logica di retry con backoff esponenziale. Tieni traccia dei tentativi usando header o code. Sposta i messaggi che falliscono dopo diversi tentativi in una coda di abbandono. Analizza questi errori per evitare perdite di dati.