Skip to content
HookDeploy

Microsoft Graph webhooks

Last verified against Microsoft Graph's documentation on September 27, 2026.

On this page ↓

Microsoft Graph sends change notifications for Outlook mail and calendars, Teams messages, OneDrive and SharePoint files, users, groups, and more. Its rules are demanding. Your URL has to echo a validation token within 10 seconds when you subscribe. Notifications need a response within 3 seconds, and Graph drops notifications for endpoints that are too slow too often. And subscriptions expire, so your app has to renew them. This page covers what Graph sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Microsoft Graph sends webhooks for

You create a subscription for a resource, such as users/{id}/messages or teams/{id}/channels/{id}/messages, and a changeType of created, updated, or deleted.

Each notification is a JSON POST with a value array. Each item has the subscriptionId, the changeType, the resource path, the clientState you set when subscribing, the tenantId, and resourceData with the item’s ID. Fetch the item from Graph to see what changed.

Subscriptions can also have a lifecycleNotificationUrl, which receives lifecycle events such as reauthorizationRequired, subscriptionRemoved, and missed.

How Microsoft Graph delivers webhooks

BehaviorDetail
ValidationOn subscribe, a POST with a validationToken query parameter. Return the decoded token as text/plain with 200 within 10 seconds
AuthenticationNo signature. Each notification carries the clientState secret you set when subscribing
Response windowA 2xx within 3 seconds. 202 Accepted if you queue the work
RetriesFailed notifications are retried with exponential backoff for up to 4 hours, with a 10-second timeout
ThrottlingIf more than 15% of responses in 10 minutes take over 10 seconds, the endpoint is marked drop and notifications are dropped for 10 minutes
ExpirySubscriptions expire and must be renewed with PATCH /subscriptions/{id}
BatchesA value array of notifications

Common Microsoft Graph webhook errors and how to fix them

Subscription creation fails

Graph’s validation request wasn’t answered in time or in the right form. It needs the decoded validationToken as plain text, with 200, within 10 seconds.

Notifications stop arriving

Either the subscription expired, or the endpoint was marked slow and notifications were dropped. Renew subscriptions before expirationDateTime, and respond within 3 seconds.

Forged notifications

Anyone can post to your URL. Compare clientState on every notification with the secret you set, and discard mismatches.

Missing changes after downtime

Graph retries for 4 hours. After a longer gap, use delta queries to catch up.

Reauthorization warnings ignored

Without lifecycle notifications, a subscription can stop delivering silently. Set a lifecycleNotificationUrl and act on reauthorizationRequired.

Why use HookDeploy with Microsoft Graph

Stay out of Graph’s drop state

HookDeploy captures every Microsoft Graph webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Graph gets its 2xx in milliseconds, whatever your processing takes, so your endpoint is never marked slow and notifications are never dropped.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

Pass validation without code

Turn on the Microsoft Graph handshake preset on the endpoint’s Security tab, under Verification (Starter and above). HookDeploy returns the validation token as plain text right away, for both the notification URL and the lifecycle notification URL.

One webhook, many systems

Send each Microsoft Graph event to your app, a reporting database, and a team channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Microsoft Graph can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so an internal tool or database in a private network can receive Microsoft Graph events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Microsoft Graph events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Renewals are still yours. HookDeploy answers validation, but it can’t renew subscriptions. Your app renews them through Graph’s API before they expire.
  • Token in the URL. The handshake preset runs after HookDeploy’s token check, so if your endpoint requires a token, subscribe with ?token= in the notification URL. HookDeploy removes it before forwarding.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Microsoft Graph treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Graph notifications carry clientState in the body, and HookDeploy forwards the body unchanged, so retries and replays can be checked exactly like the original delivery. A privacy filter that removes clientState from the stored copy would stop retries and replays from verifying.

Graph’s retries, HookDeploy’s retries, and replays can all deliver the same notification. Deduplicate on the subscription, resource, and change type, and fetch the current item from Graph before acting.

Set up Microsoft Graph with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Graph notifications) and copy its URL.
  2. On the endpoint’s Security tab, under Verification, choose Microsoft Graph and save (Starter and above).
  3. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  4. Create a subscription with POST /subscriptions, using your HookDeploy URL as the notificationUrl (and, ideally, the lifecycleNotificationUrl), and a random clientState.
  5. Make a change to the watched resource, and confirm the notification appears in HookDeploy and reaches your handler. Schedule renewals before expirationDateTime.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const expected = Buffer.from(process.env.GRAPH_CLIENT_STATE);

app.post('/webhooks/graph', express.json(), async (req, res) => {
  // HookDeploy answers validation requests, so only notifications reach this handler.
  const notifications = (req.body.value ?? []).filter((n) => {
    const got = Buffer.from(n.clientState ?? '');
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });

  res.sendStatus(202);
  for (const n of notifications) {
    await enqueue({ subscriptionId: n.subscriptionId, changeType: n.changeType, resource: n.resource,
                    lifecycleEvent: n.lifecycleEvent });
  }
  // Fetch each resource from Graph before acting, and renew on reauthorizationRequired.
});

FAQ

How do I validate a Microsoft Graph webhook subscription?

When you subscribe, Graph posts to your URL with a validationToken query parameter. Return the decoded token as text/plain with a 200 within 10 seconds. With HookDeploy, the Microsoft Graph handshake preset does this for you.

How do I verify Microsoft Graph notifications?

Graph doesn't sign basic notifications. Set a random clientState when you subscribe, and compare it with the clientState on every notification you receive.

Why did Microsoft Graph stop sending notifications?

Usually because the subscription expired, or because the endpoint was marked slow or drop after too many responses took over 10 seconds. Renew subscriptions before they expire, and respond within 3 seconds.

How long does Microsoft Graph retry notifications?

Up to 4 hours, with exponential backoff and a 10-second timeout on retries.

Does HookDeploy renew Graph subscriptions?

No. HookDeploy answers the validation request, but your app must renew subscriptions through Graph's API before they expire, and handle reauthorizationRequired lifecycle notifications.

Can the lifecycle notification URL point to HookDeploy?

Yes. Graph validates it the same way, and the Microsoft Graph handshake preset answers both.

Capture Microsoft Graph webhooks free

Start free