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.
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
changeType on each value item; lifecycleEvent on lifecycle notices POST: echo the challenge Answer within 10 seconds with 200, text/plain and the URL-decoded validationToken.
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 HTTPSnotificationUrland aclientStateyou generate. IncludelifecycleNotificationUrlnow, 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 a200withtext/plainand the URL-decoded token as the body. It validateslifecycleNotificationUrlthe same way. - Graph can't reach localhost. To test on your machine, run
hookdeck listen 3000 microsoft-graph --path /webhooks/microsoft-graphand use the URL the Hookdeck CLI prints as yournotificationUrl. 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
3 seconds for a 2xx response; retried requests get 10 seconds Retries up to 4 hours with exponential backoff, after a non-2xx response or a timeout After retries no resend documented read what changed with a delta query Duplicates not documented retries can repeat a notification, and id is optional Known failure modes
From Hookdeck's Microsoft Graph guide →-
Creating a subscription fails
Graph won't create a subscription unless your URL answers the
Test the handshake →validationTokenPOST within 10 seconds, with a200,text/plainand the URL-decoded token as the body. Returning the token still encoded fails validation. -
Notifications stop with no error
Graph deletes a subscription when it reaches
Renew subscriptions →expirationDateTime, which is 60 minutes away at most for presence and just under 30 days for OneDrive. Renew withPATCH /subscriptions/{id}, and use lifecycle notifications to catch reauthorization. -
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 → -
One POST holds several changes
Graph can batch notifications for different subscriptions into one POST, so loop over
Handle batches and duplicates →valueand handle each item separately. A retry can also repeat a notification, so make handlers safe to run twice.
Microsoft Graph webhook best practices
- Check clientState on every item.
Compare each item's
clientStatewith 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.PATCHa newexpirationDateTimebefore it passes, because Graph deletes an expired subscription. - Subscribe to lifecycle notifications.
reauthorizationRequiredwarns you before delivery pauses, for every resource.subscriptionRemovedandmissedcover 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 | 3 | 2 |
lifecycle | 3 | 3 |
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.