Hoe je betrouwbare Microsoft Graph-webhooks bouwt voor SharePoint en M365

By Mirko Peters · 2025-11-16

Bouw betrouwbare Microsoft Graph-webhooks voor SharePoint en M365 met veilige validatie, geautomatiseerde verlengingen en robuuste afleving van meldingen.

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

Betrouwbare Microsoft Graph-webhooks bouwen voor SharePoint en M365 kan ook ervaren ontwikkelaars uitdagen. Je kunt problemen tegenkomen zoals mislukte validatie als je endpoint het validatietoken niet terugstuurt of geen 200 OK-status teruggeeft. Veelvoorkomende problemen zijn endpoints die door firewalls worden geblokkeerd, netwerkmisconfiguraties of middleware die ingrijpt. Gemiste nieuwe pogingen en verlopen abonnementen komen vaak voor wanneer de service het validatieverzoek niet ontvangt of wanneer endpoints niet publiek toegankelijk zijn. Je leert hoe je deze valkuilen vermijdt en een robuuste, veilige meldingenketen bouwt, compleet met een praktische checklist en best practices.

Belangrijkste punten

• Microsoft Graph-webhooks leveren realtime meldingen over wijzigingen in Microsoft 365, zodat je niet langer constant hoeft te pollen.

• Zorg dat je webhook-endpoint publiek toegankelijk is en HTTPS gebruikt om de beveiliging en betrouwbaarheid te waarborgen.

• Reageer snel op validatieverzoeken door het validatietoken terug te sturen, zodat je webhook-abonnement succesvol wordt geactiveerd.

• Implementeer een robuuste strategie voor nieuwe pogingen en backoff om afleverfouten van meldingen op te vangen en gegevensverlies te voorkomen.

• Automatiseer het verlengen van abonnementen en monitor je webhook-keten zodat meldingen continu en betrouwbaar blijven.

Fundamenten van Microsoft Graph-webhooks

Wat zijn Microsoft Graph-webhooks

Een webhook is een HTTP-verzoek dat wordt geactiveerd door een gebeurtenis in een bronsysteem en naar een doelsysteem wordt gestuurd, vaak met een gegevenspayload. Webhooks werken automatisch: ze worden verzonden zodra hun gebeurtenis in het bronsysteem plaatsvindt.

Je gebruikt Microsoft Graph-webhooks om realtime meldingen te ontvangen over wijzigingen in je Microsoft 365-omgeving. Dat betekent dat je Microsoft Graph niet constant hoeft te bevragen op updates. In plaats daarvan krijgt je applicatie een melding zodra er iets belangrijks gebeurt. Zo blijf je up-to-date en gesynchroniseerd met gegevens die via Microsoft Graph beschikbaar zijn. Ook heb je geen pollinginfrastructuur meer nodig, waarbij je regelmatig verzoeken naar Microsoft Graph stuurt om te controleren op de nieuwste wijzigingen.

Je kunt meldingen instellen voor veel soorten gebeurtenissen, zoals:

• Berichten

• Afspraken

• Contactpersonen

• Gebruikers

• Groepen

• Gesprekken

• OneDrive-bestanden

• Waarschuwingen

Je wilt bijvoorbeeld automatisch een account aanmaken in een tijdregistratiesysteem van een derde partij wanneer een nieuwe gebruiker zich bij je organisatie aansluit. Ook kun je contentverwerking starten, zoals declaratieverwerking, wanneer iemand een nieuw bestand toevoegt aan een SharePoint-documentbibliotheek of OneDrive-map.

Waarom betrouwbaarheid ertoe doet

Microsoft Graph-webhooks spelen een sleutelrol om je SharePoint- en Microsoft 365-integraties responsief en actueel te houden. Wanneer je webhook-keten betrouwbaar werkt, reageren je applicaties in realtime op wijzigingen. Gebruikers zien altijd de meest actuele gegevens, wat hun ervaring verbetert en het risico op verouderde informatie verkleint.

Betrouwbaarheidsproblemen kunnen echter ernstige gevolgen hebben:

• Webhookfouten kunnen de functionaliteit van een applicatie aantasten als er niet goed op wordt gereageerd.

• Plotselinge pieken in verkeer kunnen servers overbelasten, wat leidt tot downtime en verlies van webhookverzoeken.

• Als webhooks niet worden verwerkt, kan dat leiden tot gegevensverlies en inconsistenties wanneer er geen mechanisme voor opnieuw verzenden is.

• Onbeveiligde webhook-URL's kunnen worden misbruikt, waardoor aanvallers corrupte gegevens kunnen versturen.

Om een robuuste oplossing te bouwen, combineer je webhooks het best met delta-queries om wijzigingen efficiënt bij te houden. Daarnaast moet je processen opzetten om abonnementen regelmatig te controleren en te verlengen. Bij bronnen die vaak wijzigen, helpt batching om de belasting te beheersen.

Webhooks instellen en valideren

Het instellen van Microsoft Graph-webhooks voor SharePoint en M365 bestaat uit verschillende belangrijke stappen. Je moet je webhook registreren, validatieaanvragen afhandelen en je eindpunt beveiligen. Elke stap speelt een cruciale rol om ervoor te zorgen dat je meldingspijplijn betrouwbaar en veilig werkt.

Microsoft Graph-webhooks registreren

Je begint met het maken van een webhookabonnement. Hiermee kan je applicatie meldingen ontvangen over wijzigingen in Microsoft 365-resources. Volg deze stappen om je webhook te registreren:

1. Maak een openbaar toegankelijk eindpunt dat HTTPS gebruikt. Dit eindpunt ontvangt meldingen van Microsoft Graph.

2. Stuur een POST-aanvraag naar het /subscriptions-eindpunt in Microsoft Graph.

3. Geef in je abonnementsaanvraag het volgende op:

   • changeType: De soorten wijzigingen die je wilt volgen, zoals "created", "updated" of "deleted".

   • notificationUrl: De URL van je webhookeindpunt.

   • resource: De resource die je wilt monitoren, zoals "/users" of "/drive/root".

   • expirationDateTime: De datum en tijd waarop het abonnement moet verlopen.

   • Optionele eigenschappen, zoals clientState, helpen je de herkomst van meldingen te verifiëren.

Voorbeeld van een abonnementsaanvraag:

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"
}

Zorg ervoor dat je eindpunt openbaar toegankelijk is en via HTTPS is beveiligd. Microsoft Graph valideert de meldings-URL voordat het abonnement wordt voltooid. Je moet abonnementen regelmatig verlengen om meldingen te blijven ontvangen. Je eindpunt moet tijdig en consistent HTTP-antwoorden geven, zodat je geen meldingen mist.

Hier is een overzicht van de vereiste velden voor registratie:

Validatieaanvragen afhandelen

Nadat je je webhook hebt geregistreerd, stuurt Microsoft Graph een validatieaanvraag naar je eindpunt. Je moet correct reageren om het abonnementsproces te voltooien. Wanneer je eindpunt een GET-aanvraag ontvangt met de queryparameter validationToken, moet je dit token als platte tekst in de responsbody terugsturen en een 200 OK-status teruggeven.

• Als je het validationToken niet terugstuurt, ontstaat er een validatiefout. Microsoft Graph kan je eindpunt dan niet bevestigen en je ontvangt geen meldingen.

• Gebruik de clientState-eigenschap om te controleren of aanvragen afkomstig zijn van je abonnement.

• Stuur het validationToken altijd binnen 10 seconden als platte tekst terug in de responsbody.

💡 Tip: Snel en correct reageren op validatieaanvragen zorgt ervoor dat je webhookabonnement zonder problemen wordt geactiveerd.

HTTPS en beveiliging van het eindpunt

Het beveiligen van je webhookeindpunt is essentieel. Microsoft Graph-webhooks vereisen HTTPS-versleuteling om gevoelige gegevens tijdens de communicatie te beschermen. Je moet inkomende aanvragen verifiëren door de handtekening te controleren die is gemaakt met een gedeelde geheime sleutel. Gebruik complexe, willekeurig gegenereerde paden voor je callback-URL's, zodat ze moeilijker te raden zijn.

• Voeg IP-whitelisting toe voor de Microsoft Graph API-eindpunten.

• Neem authenticatietokens op in de aanvraagheaders.

• Monitor je API-gebruik om ongebruikelijke patronen of pieken in activiteit te detecteren.

• Beperk de toegang tot Microsoft Graph en Outlook-API's. Alleen geautoriseerd personeel mag toegang hebben, en je moet multifactorauthenticatie afdwingen.

• Zet geavanceerde oplossingen voor endpointbeveiliging in die gedragsanalyse en machine learning gebruiken om bedreigingen te herkennen.

• Voer regelmatig beveiligingsaudits uit om kwetsbaarheden op te sporen en te verhelpen.

Elke webhook-callback gebruikt een ondertekend JSON Web Token (JWT) in de Authentication-header van de inkomende HTTPS-aanvraag. Je kunt standaard OpenID Connect-validatietechnieken voor JWT gebruiken om de integriteit van het token te waarborgen.

Je moet HTTPS gebruiken voor alle webhook-eindpunten. Deze vereiste beschermt je gegevens en zorgt voor naleving van de beveiligingsstandaarden van Microsoft. Het beveiligen van je eindpunt helpt ongeautoriseerde toegang en aanvallen te voorkomen.

Door deze stappen te volgen, zet je een betrouwbare en veilige Microsoft Graph Webhooks-pijplijn op voor SharePoint en M365. Zo zorg je ervoor dat je applicatie meldingen snel en veilig ontvangt.

Meldingen verwerken en beveiligen

Zodra je je webhook-eindpunt hebt ingesteld, moet je inkomende meldingen veilig en betrouwbaar verwerken. Deze stap zorgt ervoor dat je applicatie alleen geldige aanvragen accepteert en dat je nooit belangrijke updates van Microsoft Graph Webhooks mist.

JWT-tokens authenticeren en verifiëren

Elke melding van Microsoft Graph bevat een JSON Web Token (JWT) in de Authorization-header. Je moet dit token verifiëren voordat je een payload verwerkt. Correcte JWT-validatie beschermt je systeem tegen ongeautoriseerde of gemanipuleerde aanvragen.

Volg deze stappen om JWT-tokens te authenticeren en te verifiëren:

1. Controleer of het token niet is verlopen. Tokens bevatten een vervaltijd en je moet elk token weigeren dat na dit tijdstip valt.

2. Bevestig dat het token is uitgegeven door het Microsoft identity platform. Valideer de handtekening van het token om zeker te zijn dat het niet is gewijzigd.

3. Zorg dat de claim "audience" in het token overeenkomt met de ID van je applicatie. Deze stap bevestigt dat het token bedoeld was voor jouw app.

4. Controleer of de eigenschap azp (authorized party) overeenkomt met de verwachte waarde voor je applicatie.

Tip: Gebruik altijd betrouwbare bibliotheken voor JWT-validatie. Deze bibliotheken helpen je veelgemaakte fouten te vermijden en je applicatie veilig te houden.

Let daarnaast op veelvoorkomende beveiligingskwetsbaarheden bij het verwerken van JWT-tokens:

• Als je de JWT-handtekening niet verifieert, kunnen aanvallers de inhoud van het token ongemerkt wijzigen.

• Het gebruik van het algoritme 'none' bij het verwerken van JWT's stelt aanvallers in staat handtekeningcontroles te omzeilen.

• Zwakke ondertekeningsgeheimen maken het makkelijker voor aanvallers om geldige tokens te vervalsen.

• Aanvallers kunnen specifieke parameters in de JOSE-header injecteren om te manipuleren hoe je systeem JWT's verwerkt.

Door deze stappen en voorzorgsmaatregelen te volgen, zorg je ervoor dat alleen legitieme meldingen je applicatie bereiken.

Notificatiepayloads verwerken

Nadat je de melding hebt geauthenticeerd, moet je de payload veilig verwerken. Notificatiepayloads bevatten informatie over de gebeurtenis die de webhook heeft geactiveerd. Om de gegevensintegriteit te waarborgen en beveiligingsproblemen te voorkomen, moet je:

• Controleren of alle verplichte velden in de payload aanwezig zijn. Ontbrekende velden kunnen fouten of onvolledige verwerking veroorzaken.

• Saneer alle tekstvelden voordat je ze weergeeft of opslaat in je database. Deze stap voorkomt injectieaanvallen en gegevenscorruptie.

• Gebruik schemavalidatie om te bevestigen dat de payload overeenkomt met de verwachte structuur. Schemavalidatie helpt je onverwachte wijzigingen of onjuist opgemaakte gegevens op te sporen.

• Bereid je code voor op mogelijke wijzigingen in de API-versie. Flexibele verwerking zorgt ervoor dat je applicatie blijft werken, ook als Microsoft het formaat van de payload wijzigt.

Let op: Het valideren en saneren van payloads beschermt je systeem tegen onjuist opgemaakte gegevens en beveiligingsdreigingen.

Logica voor opnieuw proberen en backoff implementeren

Netwerkproblemen of tijdelijke storingen kunnen ervoor zorgen dat het afleveren van meldingen mislukt. Om gegevensverlies te voorkomen, heb je een robuuste strategie voor opnieuw proberen en backoff nodig. Microsoft raadt aan exponentiële backoff en gestructureerde wachtrijen te gebruiken om nieuwe pogingen te beheren.

Hier is een tabel met een samenvatting van veelgebruikte mechanismen voor opnieuw proberen en backoff:

Als je geen goede logica voor nieuwe pogingen en backoff implementeert, loop je het risico dat je meldingen verliest of dat er inconsistenties in je gegevens ontstaan. Mislukte aanvragen of rate limiting kunnen ervoor zorgen dat je belangrijke updates niet ontvangt. Exponential backoff helpt je om aanvragen die worden gethrottled te beheren en verkleint de kans dat je systeem of Microsoft Graph Webhooks overbelast raken.

🛡️ Best practice: Houd altijd bij hoeveel nieuwe pogingen er zijn gedaan en verplaats mislukte berichten na enkele pogingen naar een abandon-wachtrij. Zo kun je aanhoudende problemen onderzoeken en oplossen zonder gegevens te verliezen.

Door JWT-tokens te authenticeren, payloads te valideren en betrouwbare logica voor nieuwe pogingen te implementeren, bouw je een veilige en robuuste meldingenpijplijn. Met deze stappen verwerk je elke melding van Microsoft Graph Webhooks veilig en efficiënt.

Abonnementen beheren en wijzigingen bijhouden

Automatisch vernieuwen van abonnementen

Je moet je webhookabonnementen actief houden om te voorkomen dat je meldingen mist. Microsoft Graph-abonnementen verlopen na een vastgestelde periode. Als je ze niet vernieuwt, ontvangt je applicatie geen updates meer. Je kunt het vernieuwen op verschillende manieren automatiseren:

• Stuur HTTP PATCH-aanvragen om de vervaldatum van elk abonnement bij te werken.

• Plan deze PATCH-aanvragen dagelijks. Zo blijven je abonnementen actueel en voorkom je onverwachte verlopen.

• Houd de vervaltijdstempel van elk abonnement bij. Vernieuw elk abonnement dat bijna verloopt.

• Als een abonnement verloopt, maak dan meteen een nieuw abonnement aan om de meldingsstroom te herstellen.

Tip: Door vernieuwingen te automatiseren, bespaar je handmatig werk en blijft je systeem verbonden met Microsoft Graph.

Monitoring en waarschuwingen

Je moet de gezondheid van je webhookpijplijn bewaken. Stel waarschuwingen in die je informeren als een abonnement niet kan worden vernieuwd of als je endpoint niet meer reageert. Gebruik logging om binnenkomende meldingen en vernieuwingspogingen bij te houden. Zo zie je problemen al voordat ze gebruikers raken.

• Houd de status en vervaldatums van abonnementen in de gaten.

• Stel waarschuwingen in voor mislukte vernieuwingen of gemiste meldingen.

• Log alle webhookgebeurtenissen en fouten voor probleemoplossing.

🛎️ Proactieve monitoring helpt je problemen snel op te lossen en houdt je integratie betrouwbaar.

Delta-query's gebruiken voor het bijhouden van wijzigingen

Met delta-query's houd je wijzigingen bij in SharePoint- en M365-resources, en dat op een efficiënte manier. Je kunt ze gebruiken om alleen nieuwe of bijgewerkte gegevens te ontvangen. Dat vermindert de noodzaak voor frequent pollen en verkleint het risico op throttling.

• Met delta-query's kan je applicatie wijzigingen bijhouden zonder elke keer alle gegevens te downloaden.

• Ze werken goed met SharePoint en M365 en sturen alleen een melding wanneer er iets verandert.

• Door delta-query's te gebruiken, bespaar je bandbreedte en verbeter je de prestaties.

Delta-query's hebben echter enkele beperkingen:

Let op: Test je delta-queryimplementatie altijd grondig om met deze beperkingen om te gaan en nauwkeurige wijzigingsregistratie te garanderen.

Door vernieuwingen te automatiseren, je pijplijn te bewaken en delta-query's te gebruiken, bouw je een betrouwbaar en efficiënt webhooksysteem voor SharePoint en M365.

Je bouwt betrouwbare Microsoft Graph-webhooks door een duidelijk proces te volgen. Begin met het aanmaken van abonnementen en het gebruik van delta-queries om wijzigingen bij te houden. Automatiseer de verlengingen en monitor je pipeline op problemen. Geef bij elke stap prioriteit aan validatie, beveiliging en veerkracht. Gebruik voor de productiegereedheid deze checklist:

• Houd de documentatie up-to-date en zorg dat de supportteams op de hoogte blijven.

• Plan regelmatige controles op de status van je abonnementen.

• Gebruik beveiligingsscans in je CI-pipeline en houd auditlogs bij.

Pas deze best practices toe zodat je SharePoint- en M365-integraties betrouwbaarblijven.

Veelgestelde vragen

Hoe verläng je een verlopen Microsoft Graph-webhookabonnement?

Je stuurt een PATCH-aanvraag naar het eindpunt /subscriptions/{id} van Microsoft Graph. Werk het veld expirationDateTime bij. Plan dit proces dagelijks in. Zo blijven je abonnementen actief en mis je geen meldingen.

Wat moet je doen als je webhookeindpunt de validatie niet doorstaat?

Controleer of je eindpunt de validationToken als platte tekst teruggeeft in de responsbody. Reageer met de statuscode 200 OK. Zorg dat je eindpunt publiek toegankelijk is en HTTPS gebruikt.

Hoe beveilig je je webhookeindpunt?

Gebruik HTTPS voor alle eindpunten. Valideer JWT-tokens in elke aanvraag. Beperk de toegang met authenticatie en een IP-whitelist. Houd het systeem in de gaten op ongebruikelijke activiteit. Controleer je beveiligingsinstellingen regelmatig.

Waarom moet je delta-queries gebruiken met webhooks?

Delta-queries helpen je om alleen nieuwe of gewijzigde gegevens bij te houden. Dit beperkt het gebruik van bandbreedte en verbetert de prestaties. Je hoeft niet elke keer alle gegevens te downloaden, waardoor je integratie sneller en efficiënter werkt.

Wat is de beste manier om mislukte webhookmeldingen af te handelen?

Implementeer retry-logica met exponentiële backoff. Houd het aantal pogingen bij via headers of wachtrijen. Verplaats berichten die na meerdere pogingen nog steeds mislukken naar een abandon-wachtrij. Onderzoek deze fouten om gegevensverlies te voorkomen.