# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill microsoft-graph-webhooks` ([details](https://hookdeck.com/webhooks/microsoft-graph/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Microsoft Graph's official docs](https://learn.microsoft.com/en-us/graph/api/resources/changenotification).

[Overview](https://hookdeck.com/webhooks/microsoft-graph) · [Webhook events (6)](https://hookdeck.com/webhooks/microsoft-graph/events) · [MCP events](https://hookdeck.com/webhooks/microsoft-graph/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/microsoft-graph/verify) · [Production guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/microsoft-graph/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `None (unsigned)` | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks) |
| How events are identified | `changeType on each value item; lifecycleEvent on lifecycle notices` | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/api/resources/changenotification) |
| Body format | `JSON` | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks) |
| Event families | `change notifications, lifecycle notifications` | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/api/resources/changenotification) |
| URL handshake | `POST: echo the challenge` Answer within 10 seconds with 200, text/plain and the URL-decoded validationToken. | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks) |
| Envelope | `value, validationTokens` | [Microsoft Graph docs](https://learn.microsoft.com/en-us/graph/api/resources/changenotification) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill microsoft-graph-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/microsoft-graph/skill) |

[Verify Microsoft Graph webhooks](https://hookdeck.com/webhooks/microsoft-graph/verify)

## 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.

## 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](https://learn.microsoft.com/en-us/graph/delta-query-overview).

## Delivery behaviour

- **Timeout:** 3 seconds. for a 2xx response; retried requests get 10 seconds. [Guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 4 hours. with exponential backoff, after a non-2xx response or a timeout. [Guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** no resend documented. read what changed with a delta query. [Guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** not documented. retries can repeat a notification, and `id` is optional. [Guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#testing)
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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#other-limits)
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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#timeouts)
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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#duplicates)

From [Hookdeck's Microsoft Graph guide](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts).

## Microsoft Graph webhook best practices

- **[Check clientState on every item](https://hookdeck.com/webhooks/microsoft-graph/verify).** 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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#timeouts).** Queue the notification and return a `202`. Slow responses first delay your notifications, then get them dropped for good.
- **[Renew before the subscription expires](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#other-limits).** Each notification carries `subscriptionExpirationDateTime`. `PATCH` a new `expirationDateTime` before it passes, because Graph deletes an expired subscription.
- **[Subscribe to lifecycle notifications](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#other-limits).** `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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/microsoft-graph/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/microsoft-graph/events#created): A resource you subscribed to is created
- [updated](https://hookdeck.com/webhooks/microsoft-graph/events#updated): A resource you subscribed to is updated
- [deleted](https://hookdeck.com/webhooks/microsoft-graph/events#deleted): A resource you subscribed to is deleted

### Lifecycle notifications

- [reauthorizationRequired](https://hookdeck.com/webhooks/microsoft-graph/events#reauthorizationRequired): The subscription needs reauthorizing before notifications pause
- [subscriptionRemoved](https://hookdeck.com/webhooks/microsoft-graph/events#subscriptionRemoved): Graph removes the subscription, so create a new one
- [missed](https://hookdeck.com/webhooks/microsoft-graph/events#missed): Some change notifications weren't delivered, so resync

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [change](https://hookdeck.com/webhooks/microsoft-graph/events#resource-change) | 3 | 2 |
| [lifecycle](https://hookdeck.com/webhooks/microsoft-graph/events#resource-lifecycle) | 3 | 3 |

[All 6 events](https://hookdeck.com/webhooks/microsoft-graph/events)

## In this hub

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

Not affiliated with Microsoft Graph. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/microsoft-graph.json) · [Report a correction](https://hookdeck.com/contact)
