Microsoft Graph webhooks

Microsoft Graph webhooks, which Microsoft calls change notifications, are JSON POSTs that Graph sends to your HTTPS endpoint when a resource you subscribed to, such as a mailbox, a Teams chat or a OneDrive folder, is created, updated or deleted.

6 events covered

How Microsoft Graph webhooks work

Change notifications save you polling Graph, which can run into its throttling limits. You create a subscription with POST /subscriptions, naming a resource, one or more changeType values and a notificationUrl. Graph checks the URL with a validationToken request, then POSTs to it when that resource changes. Subscriptions expire, at most 60 minutes out for presence and just under 30 days for OneDrive, so your app has to renew them.

The body is a value array, and one POST can carry changes from several subscriptions. Each item has a changeType, the resource it applies to, its subscriptionId and your clientState, and you need resource and changeType together to know what happened. A basic notification gives you an ID to fetch, while a rich notification, which you opt into with includeResourceData, adds an encryptedContent object and top-level validationTokens. Lifecycle notifications use the same envelope with lifecycleEvent in place of changeType, and go to your lifecycleNotificationUrl. Notifications carry no API version.

Key facts

Signature header
None (unsigned)
How events are identified
changeType on each value item; lifecycleEvent on lifecycle notices
Event families
change notifications, lifecycle notifications
URL handshake
POST: echo the challenge

Answer within 10 seconds with 200, text/plain and the URL-decoded validationToken.

Envelope
value, validationTokens
Agent skill
npx skills add hookdeck/webhook-skills --skill microsoft-graph-webhooks

Verify Microsoft Graph webhooks →

Setting up Microsoft Graph webhooks

  • Graph has no dashboard for this. Create each subscription through the API or an SDK with POST /subscriptions, a public HTTPS notificationUrl and a clientState you generate. Include lifecycleNotificationUrl now, because you can't add it to an existing subscription.
  • Answer the validation request, because Graph doesn't create the subscription otherwise. It POSTs to your URL with ?validationToken=..., and you have 10 seconds to return a 200 with text/plain and the URL-decoded token as the body. It validates lifecycleNotificationUrl the same way.
  • Graph can't reach localhost. To test on your machine, run hookdeck listen 3000 microsoft-graph --path /webhooks/microsoft-graph and use the URL the Hookdeck CLI prints as your notificationUrl. Then change something in the resource, such as sending a message to a mailbox you subscribed to.
  • Microsoft's docs describe no way to resend a notification. To catch up after a gap, read what changed with a delta query.

Delivery behaviour

  1. Creating a subscription fails

    Graph won't create a subscription unless your URL answers the validationToken POST within 10 seconds, with a 200, text/plain and the URL-decoded token as the body. Returning the token still encoded fails validation.

    Test the handshake →
  2. Notifications stop with no error

    Graph deletes a subscription when it reaches expirationDateTime, which is 60 minutes away at most for presence and just under 30 days for OneDrive. Renew with PATCH /subscriptions/{id}, and use lifecycle notifications to catch reauthorization.

    Renew subscriptions →
  3. Slow responses lose notifications

    When over 10% of responses in 10 minutes take longer than 3 seconds, Graph delays new notifications by 10 minutes. When over 15% take longer than 10 seconds, it drops them for 10 minutes, and those can't be recovered.

    Acknowledge in time →
  4. One POST holds several changes

    Graph can batch notifications for different subscriptions into one POST, so loop over value and handle each item separately. A retry can also repeat a notification, so make handlers safe to run twice.

    Handle batches and duplicates →

Microsoft Graph webhook best practices

  • Check clientState on every item. Compare each item's clientState with the value you set for that subscription, and ignore any that don't match. On a basic notification, it's the only check you have.
  • Acknowledge within 3 seconds. Queue the notification and return a 202. Slow responses first delay your notifications, then get them dropped for good.
  • Renew before the subscription expires. Each notification carries subscriptionExpirationDateTime. PATCH a new expirationDateTime before it passes, because Graph deletes an expired subscription.
  • Subscribe to lifecycle notifications. reauthorizationRequired warns you before delivery pauses, for every resource. subscriptionRemoved and missed cover fewer resources, so check they apply to yours.
  • Process each item separately. Loop over value, since one POST can batch several subscriptions, and make handlers safe to run twice, since retries can repeat a notification.
  • Resync with a delta query. Dropped notifications can't be recovered, so treat webhooks as a prompt and use a delta query to find anything they missed.

Common Microsoft Graph webhook events

Change notifications

created A resource you subscribed to is created
updated A resource you subscribed to is updated
deleted A resource you subscribed to is deleted

Lifecycle notifications

reauthorizationRequired The subscription needs reauthorizing before notifications pause
subscriptionRemoved Graph removes the subscription, so create a new one
missed Some change notifications weren't delivered, so resync

Events by resource

Resource Events Payloads
change

created · updated · deleted

3 2
lifecycle

missed · subscriptionRemoved · reauthorizationRequired

3 3

All 6 events →

In this hub

Webhook events → Every covered Microsoft Graph event, with payloads where the registry has them.
MCP events → How an agent subscribes to Microsoft Graph events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill microsoft-graph-webhooks

Keep a slow handler from getting your Graph notifications dropped.

Hookdeck Event Gateway answers Graph's validation request, accepts each notification, queues it and retries to your service on your schedule, so your handler can take as long as it needs.

Not affiliated with Microsoft Graph. Facts are compiled from public sources and linked inline.