Microsoft Office Add-In Developer

The EWS Cutover Runbook: Going Live on Microsoft Graph During the Phased EWS Retirement

The EWS Cutover Runbook: Going Live on Microsoft Graph During the Phased EWS Retirement

Correction, 3 October 2026: An earlier version of this article described 1 October 2026 as a single hard cut-off after which EWS stopped serving Outlook add-ins, and said EWS could not be a rollback target after that date. That was not correct. Microsoft is retiring EWS in Exchange Online in phases: the deprecation began on 1 October 2026, with app allow lists required from 10 October and tenants then switched off individually with seven days’ warning, and EWS is fully and permanently disabled from 1 April 2027. Until then, whether EWS can serve as a rollback depends on each tenant’s settings. The earlier version also described nested app authentication as an on-behalf-of exchange and placed Graph permissions in the unified manifest. The article has been corrected throughout.

Microsoft’s retirement of Exchange Web Services (EWS) in Exchange Online is under way. The Exchange Team announced on 1 October 2026 that “The deprecation of EWS in Exchange Online starts today”, and it proceeds in phases, tenant by tenant, until 1 April 2027, from which date EWS in Exchange Online is “fully and permanently disabled”. The legacy Exchange Online callback tokens that Outlook add-ins used to reach EWS from their back ends are already turned off across all Microsoft 365 tenants. If you have already planned and built your migration, the remaining risk is no longer architectural — it is operational. This is the Outlook add-in cutover runbook: the precise sequence of pre-flight checks, traffic switch-over steps, rollback triggers and post-go-live validation that turns a tested EWS to Microsoft Graph migration into a safe, boring, uneventful go-live. A phased retirement is not a gentle taper from your side: you do not control when, or whether, a given customer’s tenant loses EWS access before the final date, and every Exchange Online tenant reaches the same end point. Treat the cutover like a production change with named owners and go/no-go gates, and it is far more likely to pass without drama.

What this runbook assumes you have already done

A runbook is not a migration guide. We assume the heavy lifting is behind you and that the following are in place before you read on:

  • A Graph-backed code path for every EWS call your add-in makes — mail (/me/messages, /me/mailFolders), calendar (/me/events, /me/calendarView), and contacts (/me/contacts) — replacing the equivalent EWS FindItem, GetItem and CreateItem operations.
  • Authentication reworked from getCallbackTokenAsync and EWS callback tokens to nested app authentication (NAA), in which MSAL.js acquires Microsoft Graph tokens in the add-in’s client code without the need for a middle-tier server. This step is not optional: Microsoft has turned legacy Exchange Online callback tokens off across all Microsoft 365 tenants. Where NAA is not supported on a host you must serve, you have a documented fallback; Microsoft describes legacy single sign-on through getAccessToken, with a server-side on-behalf-of exchange, as the pattern for older clients without NAA.
  • An app registration in Entra ID with the correct delegated Graph scopes (Mail.Read, Mail.ReadWrite, Calendars.ReadWrite, Contacts.Read as applicable), admin consent secured, and the single-page application redirect URI (brk-multihub:// followed by your add-in’s domain) that NAA requires.
  • If you intend to keep EWS as a rollback path for any tenant, an EWS code path that authenticates with Entra ID tokens rather than callback tokens, and a record, tenant by tenant, of whether EWS is still available to it. Wherever a tenant has EWSEnabled set to True, the app ID that path uses must be on the tenant’s EWSAllowedAppIDs allow list (see the rollback section for why this matters).
  • Any EWS streaming or push subscriptions replaced by Microsoft Graph change notifications (webhooks), with a public notification endpoint, validation token handling and subscription renewal already tested.
  • A manifest strategy decided. Whether you are on the unified manifest or the add-in only (XML) manifest, the manifest you intend to publish is built and version-stamped. With NAA, Graph scopes are requested at runtime through MSAL rather than declared in the manifest. If any host falls back to legacy getAccessToken single sign-on, confirm the manifest’s webApplicationInfo (unified) or WebApplicationInfo (XML) entry matches your app registration.

If any of those are not true, stop. This is not the document you need — you need the migration sprint first, and soon: in Microsoft’s announced next phase, tenants still on the default EWS setting are switched off one at a time with only seven days’ warning.

The cutover model: feature flags, not a manifest swap

The single most important decision in this runbook is not to perform the cutover by republishing a manifest. Manifest changes made through centralised deployment and the Microsoft 365 admin centre do not take effect immediately: Microsoft notes that centrally deployed add-ins can take 24 to 72 hours to appear on the ribbon, and an updated line-of-business manifest reaches each user the next time they start the application. In our view that is far too slow and uneven to serve as a rollback mechanism. If your rollback plan is “republish the old manifest”, you do not have a rollback plan.

Instead, ship a single add-in build that contains both code paths — EWS and Graph — and select between them at runtime with a server-controlled feature flag. The flag is the cutover switch. This gives you three properties you cannot get any other way:

  1. Controlled traffic cutover. You move users from EWS to Graph in rings, by percentage or by cohort, rather than all at once.
  2. Instant rollback. Flipping the flag back is a configuration change that takes effect on the next add-in activation, with no store, no admin centre and no manifest cache in the path, provided the path you roll back to still works for that tenant (see the rollback section).
  3. Decoupling of deploy from release. The risky binary is already in production days before go-live, fully baked and warm; cutover day only changes a flag.

Design the flag to be evaluated server-side and delivered to the client at activation, with a sensible cached default so that a flag-service outage fails to a known, safe state. Plan that default deliberately, and per tenant. “EWS” is a safe default only for a tenant in which EWS is still available to your app (see the rollback section below); for any tenant where you cannot confirm that, fail-safe must mean “Graph”. As 1 April 2027 approaches, when Microsoft fully and permanently disables EWS in Exchange Online, it must mean “Graph” for every Exchange Online tenant.

Pre-cutover readiness checklist

Run this in the days before go-live. Every item is binary — done or not done — and every item has an owner.

Code and configuration

  • [ ] Dual-path build deployed to production and confirmed serving the correct version hash.
  • [ ] Feature flag service live, tested, and reachable from the add-in’s runtime origin (CORS confirmed).
  • [ ] Graph app registration consented in the production tenant.
  • [ ] For every tenant where you are keeping an EWS rollback path: EWSEnabled and the EWSAllowedAppIDs allow list confirmed to permit your app, and the result recorded against the ring plan.
  • [ ] NAA confirmed working on the minimum supported Outlook builds (new Outlook for Windows, classic Outlook, Outlook on the web, Mac). Fallback auth path documented for any build where NAA is unavailable.
  • [ ] Graph change-notification subscriptions created against production, with renewal jobs scheduled and validated.

Observability

  • [ ] Telemetry dashboards built and showing live traffic: per-path success rate, error rate, p50/p95 latency, and token-acquisition failure rate, all split by EWS vs Graph and by client host.
  • [ ] Alerts wired with thresholds agreed (see telemetry section below).
  • [ ] Log correlation IDs flowing from client through to Graph call, so a single failing user session can be traced end to end.

People and process

  • [ ] Go/no-go gates scheduled with named owners (table below).
  • [ ] Hypercare rota staffed for the full 72 hours.
  • [ ] User and helpdesk communications drafted, approved and queued.
  • [ ] Rollback procedure rehearsed at least once in a non-production ring.

Go/no-go gate table

Gates are checkpoints with an explicit owner and an explicit decision. No gate passes by default or by silence. If an owner is unavailable, the gate fails.

Gate Owner Pass criteria If failed
G0 — Build & config frozen Release Engineer Dual-path build live; flag service healthy; change freeze in effect Halt; no cutover until resolved
G1 — Telemetry green baseline Observability Lead 24h of clean baseline; dashboards and alerts confirmed firing on test events Delay cutover; fix instrumentation first
G2 — Auth verified Identity Engineer NAA token acquisition (and any fallback auth path) succeeding across all supported hosts; token failure rate < 0.5% Hold at current ring; do not advance
G3 — Canary healthy Cutover Lead Canary ring (1–2%) on Graph for ≥ 2h within error and latency budget Roll back canary; investigate
G4 — Ring expansion Cutover Lead Each ring meets budget for its soak window before the next opens Pause expansion; hold or roll back
G5 — Full cutover Service Owner 100% on Graph; EWS traffic at zero; all metrics within budget Roll back to last healthy ring
G6 — Hypercare exit Service Owner 72h stable; no open Sev-1/Sev-2; subscriptions renewing Extend hypercare

Order of operations on switch-over day

Run the day from a single shared timeline with one Cutover Lead who owns the go/no-go calls. Everyone else advises; the Lead decides.

  1. T-minus 60: confirm freeze and baseline. Pass G0 and G1. Verify no other change is landing in the same window — no infrastructure deploys, no Entra changes, no manifest republish.
  2. T-minus 30: auth smoke test. Manually drive a Graph call through the live add-in on each supported host. Pass G2.
  3. T-zero: open the canary. Flip the feature flag to route 1–2% of activations onto the Graph path. Choose the canary cohort deliberately — internal users or a friendly pilot group, not your largest customer. Watch live for the agreed soak window (G3).
  4. Ring expansion. Advance the flag through pre-agreed rings — for example 2% → 10% → 25% → 50% → 100%. Each ring soaks for its window and must clear its budget before the next opens (G4). Resist the temptation to skip rings because “it looks fine”; the value of rings is catching the slow-burning problem — subscription renewal failures, throttling under load, a host-specific token bug — that only appears at scale.
  5. Watch for throttling at scale. Microsoft Graph throttles Outlook resources per app ID and mailbox combination, and applies global per-app limits on top. A pattern that was invisible at 2% — a back-end sync job, for example, or many users working against the same shared mailbox — can trip 429 responses with Retry-After headers at 50%. Confirm your client honours Retry-After and backs off; if 429 rates climb, hold the ring rather than pushing through.
  6. Full cutover and EWS drain. At 100%, confirm EWS traffic falls to zero on the dashboard (G5). Zero EWS calls is the real success signal — not merely high Graph success rates. A residual trickle of EWS means a code path or a client cohort you have not accounted for.
  7. Enter hypercare. Declare the cutover complete, announce it on the incident channel, and start the 72-hour clock.

Rollback triggers and procedure

Decide the triggers before go-live, write them down, and empower the on-call engineer to act on them without waiting for a meeting. Ambiguity is what turns a five-minute rollback into a two-hour outage.

Roll back immediately if any of these breach for more than the stated dwell time:

  • Graph call error rate exceeds baseline by more than 2 percentage points for 5 minutes.
  • Token acquisition failure rate exceeds 2% for 5 minutes (the classic signature of an NAA or consent problem).
  • p95 latency on the Graph path exceeds twice the EWS baseline for 10 minutes.
  • 429 throttling rate climbs steadily despite correct backoff.
  • Any Sev-1: add-in fails to load, or a core user task (read message, create event) is broken for the active ring.

Rollback procedure:

  1. The on-call engineer flips the feature flag for the affected ring (or globally): back to EWS for tenants where the EWS path is confirmed available (see below), and back to the last healthy Graph configuration everywhere else. This is the whole of the technical rollback and takes effect on next activation — typically seconds to a couple of minutes.
  2. Announce the rollback on the incident channel with the trigger that fired and the rings affected.
  3. Confirm on the dashboard that traffic has moved to the rollback target and error rates have recovered.
  4. Freeze further expansion. Capture logs and correlation IDs while they are fresh.
  5. Triage to root cause before any re-attempt. Do not re-flip the flag hopefully.

EWS is a conditional fallback, and it has an end date. Flipping the flag back to EWS only helps if EWS will actually answer for that tenant, and in Exchange Online that can no longer be assumed:

  • Callback tokens are already off. Microsoft states that legacy Exchange Online user identity tokens and callback tokens “are no longer supported and turned off across all Microsoft 365 tenants”. An EWS path that authenticates with getCallbackTokenAsync is not a rollback target at all; only an EWS path that uses Microsoft Entra ID (OAuth) tokens can be.
  • The tenant must still permit EWS for your app. The deprecation began on 1 October 2026. From 10 October, in Microsoft’s worldwide cloud, a tenant with EWSEnabled set to True must have an EWSAllowedAppIDs allow list, and only the apps on it can use EWS, so your app ID must be on that tenant’s list. In the next phase, worldwide-cloud tenants still at the default (Null) are set to False one at a time, each after a seven-day warning in Message Center. Until the final shutdown a tenant admin can re-enable EWS, either by setting EWSEnabled to True with your app ID on the allow list or by setting it back to Null. But that is the customer’s admin acting, not your on-call engineer, and it is not instant: Microsoft says EWSEnabled changes typically apply within an hour but can take up to four, and allow-list changes take 24 hours.
  • It ends on 1 April 2027. From that date, Microsoft says, EWS in Exchange Online will be “fully and permanently disabled” and the ability to control EWSEnabled is removed from tenant admins: “There will be no exceptions past April 2027.” After that there is no EWS fallback for Exchange Online mailboxes. (EWS in on-premises Exchange Server is not affected.)

In practice, treat the EWS rollback as something that exists per tenant, not globally. Before go-live, establish each target tenant’s EWSEnabled value and whether your app is on its allow list, and re-check before each ring opens, because Microsoft selects tenants for switch-off individually during the second phase. For any tenant where EWS is not confirmed available, and for every Exchange Online tenant as April 2027 approaches, your rollback target is the previous healthy Graph configuration and your contingency is forward-fix, not retreat.

Communication plan for affected users

A silent cutover is a successful cutover for the user — but only if you have prepared the people around it.

  • Helpdesk and support receive a one-page brief before T-zero: what is changing, the symptoms of the known failure modes, the rollback decision-maker, and the escalation path. They should not learn about the cutover from the first ticket.
  • End users generally need nothing during a clean cutover, and you should avoid alarming them. Prepare a short, plain-English notice to send only if a re-authentication prompt or visible change is expected on their host — for example, a one-time consent prompt the first time the Graph path runs.
  • Stakeholders and the service owner get scheduled checkpoints aligned to the gates, not a running commentary. Agree in advance what “green” looks like so updates are short.
  • A standing incident channel is the single source of truth for the cutover team for the whole window, including the 72-hour hypercare.

Post-cutover validation suite

When you hit 100%, run a scripted validation pass rather than eyeballing the dashboard. Cover every operation your add-in performs:

  • Mail: read a message body and headers, list a folder, send or save a draft, and — if you write — apply a category or move an item. Confirm against /me/messages and /me/mailFolders.
  • Calendar: read an event, query a date range via /me/calendarView, and create and update an event via /me/events, including time-zone handling, which can differ subtly between your EWS and Graph code paths.
  • Contacts: read and search /me/contacts if in scope.
  • Change notifications: trigger a real change on a subscribed resource and confirm your webhook receives it, validates correctly and renews on schedule. This is the path that replaces your EWS streaming subscriptions, and it has its own failure modes.
  • Auth across hosts: repeat the core flow on new Outlook for Windows, classic Outlook, Outlook on the web and Mac, confirming token acquisition succeeds on each, through NAA or through your documented fallback where NAA is not supported.
  • Negative cases: revoke and re-grant consent on a test account; confirm the add-in handles a 401/consent prompt gracefully rather than failing opaquely.

Keep this suite scripted so it can be re-run on demand throughout hypercare.

The 72-hour hypercare window

The cutover is not finished when traffic reaches 100%. The first three days expose the problems that only daily working patterns reveal — Monday-morning calendar load, overnight subscription renewals, weekly batch behaviours, and the long tail of Outlook clients that activate infrequently.

During hypercare:

  • Keep the on-call rota staffed and the rollback authority unambiguous around the clock.
  • Hold short stand-ups at the start of each day to review overnight telemetry and ticket trends.
  • Watch subscription renewal jobs specifically — a webhook subscription that silently fails to renew will quietly stop delivering notifications, and the symptom (stale data) is easy to miss.
  • Keep the feature flag in place and operational. Do not remove the EWS code path or the flag until hypercare exits cleanly at G6. After that, the EWS path is worth keeping only while it remains a usable fallback for some of your tenants. For Exchange Online it stops being one on 1 April 2027, so plan its removal before then. (If you also serve mailboxes on on-premises Exchange Server, where EWS is unaffected, that is a separate decision.)
  • Exit only on the Service Owner’s call against G6: 72 hours stable, no open Sev-1 or Sev-2, subscriptions renewing, and EWS traffic confirmed at zero.

Telemetry to watch throughout

Across every phase, four signals tell you whether the cutover is healthy, each split by code path and by client host:

  • Success rate — the proportion of Graph calls returning success. Your headline indicator.
  • Error rate — non-success responses, broken out by status. A rising 403 rate points to scope or consent; 429 points to throttling; 404 may signal an endpoint or ID-translation bug between EWS and Graph identifiers.
  • Latency — p50 and p95. Graph and EWS have different performance profiles; know your baselines so you can tell a real regression from a normal difference.
  • Token acquisition failure rate — the single best early-warning signal for authentication problems (NAA, consent or Conditional Access), and the metric most worth a tight alert threshold.

The decisive signal at full cutover is EWS call volume trending to zero. As long as any EWS traffic remains, some part of your estate is still depending on an API that Microsoft is switching off tenant by tenant in Exchange Online, and that is fully and permanently disabled there from 1 April 2027.

How McKenna Consultants can help

We can help you plan and run an EWS to Microsoft Graph cutover as a focused, fixed-scope engagement. If you have already built the Graph code path, you may not need a long migration programme: what remains is landing it safely, without an outage. That is the work this runbook describes, and the work we can do alongside your team: instrumenting the dual-path build and feature flags, standing up the telemetry and alerts, establishing which of your tenants still have a usable EWS fallback, defining the go/no-go gates and rollback triggers, and running the cutover and 72-hour hypercare.

McKenna Consultants is a UK Office add-in development consultancy. For Workiro, we built an Outlook add-in alongside a Microsoft Graph API server-side integration that syncs email conversations into their platform. We can work with your team across the unified manifest, nested app authentication and Microsoft Graph change notifications, join late, and help de-risk your EWS to Microsoft Graph migration.

If you have an Outlook add-in still talking to EWS in Exchange Online, get in touch for a short readiness review and a fixed-scope cutover plan. Tenants still on the default setting can be switched off with seven days’ notice, and from 1 April 2027 there is no way back; it is far better to go live calmly on your own schedule than to firefight when a customer’s tenant loses EWS.

Sources

Related Articles

Related Case Studies

View all case studies

Have a question about this topic?

Our team would be happy to discuss this further with you.

Get in Touch