microsoft-graph-webhooks

Microsoft Graph Webhooks

Microsoft Graph delivers change notifications (webhooks) when a resource you subscribe to — Outlook messages, Teams chatMessages, OneDrive/SharePoint driveItems, users, groups, presence, and more — is created, updated, or deleted. There is no HMAC signature and it does not follow the Standard Webhooks spec. Instead, Graph uses a three-part validation model.

When to Use This Skill

• How do I receive Microsoft Graph webhooks / change notifications?
• How do I respond to the validationToken endpoint validation handshake?
• How do I validate the clientState on a Microsoft Graph notification?
• How do I create/renew a Microsoft Graph subscription (they expire fast)?
• How do I decrypt rich notifications with includeResourceData: true?
• How do I handle lifecycle notifications (reauthorizationRequired, subscriptionRemoved, missed)?
• Why is my Microsoft Graph subscription creation failing validation?

The Three-Part Validation Model

1. Endpoint validation handshake — On subscription create (and when the notificationUrl changes), Graph sends POST <notificationUrl>?validationToken={token} with an empty body. You must echo the URL-decoded token back as text/plain with HTTP 200 within 10 seconds, or the subscription is not created.
2. clientState — An opaque shared secret (max 128 chars) you set when creating the subscription. Graph echoes it in the clientState field of every notification. Compare it (timing-safe) to your stored value and reject mismatches — this is what authenticates ordinary notifications.
3. validationTokens (rich notifications only) — When you subscribe with includeResourceData: true, each POST includes a validationTokens array of JWTs signed by the Microsoft identity platform, and the resource data is AES-encrypted. See references/verification.md.

Verification (core)

The two checks every handler needs — the handshake and the clientState compare: