The EWS Cutover Runbook: Your Go-Live Plan for the October 1 2026 Deadline

The EWS Cutover Runbook: Your Go-Live Plan for the October 1 2026 Deadline

The clock now reads under 90 days. On 1 October 2026, Exchange Web Services stops serving Outlook add-ins, and any add-in still calling EWS callback tokens will start failing in the field. 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. The EWS deprecation October 2026 milestone is unforgiving precisely because it is a hard cut, not a gentle taper. Treat the cutover like a production change with named owners and go/no-go gates, and it will 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), which performs the on-behalf-of token exchange in the browser without a server round-trip. Where NAA is not yet available across all your target Outlook builds, you have a documented interim plan.
• 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 add-in’s AppID added to the tenant AppID AllowList as a temporary measure where your organisation gates which add-ins may request tokens.
• 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. If you have moved to the unified (JSON) manifest, your Graph permissions and runtime configuration live there; if you are still on the XML add-in manifest, you have confirmed your WebApplicationInfo and requested scopes are correct. Either way, the manifest you intend to publish is built and version-stamped.

If any of those are not true, stop. This is not the document you need — you need the migration sprint, and you need it this week.

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 propagation through centralised deployment and the Microsoft 365 admin centre is slow, partially cached and effectively irreversible on a useful timescale. 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.
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: before the deadline, fail-safe means “EWS”; in the final days before 1 October, fail-safe must flip to “Graph”, because EWS will shortly cease to be a safe fallback at all.

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; AppID present on the AllowList where required.
• [ ] 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 / on-behalf-of token exchange 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. Graph applies per-app and per-mailbox throttling. A pattern that was invisible at 2% 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 back to EWS for the affected ring (or globally). 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 returned to EWS 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.

The one caveat, which sharpens as the deadline nears: in late September, rolling back to EWS buys you only days. Past 1 October, EWS is not a fallback — it is simply broken. Your rollback target in the final week is therefore “previous Graph ring”, 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 the time-zone handling that so often differs subtly from EWS.
• 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. EWS streaming subscriptions are gone; this is the path that replaces them 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 the on-behalf-of exchange succeeds on each.
• 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 — and, given the deadline, only retire EWS code after 1 October has passed without incident.
• 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 NAA and on-behalf-of problems, 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 disappears on 1 October.

How McKenna Consultants can help

We run EWS cutovers as a packaged, compressed-timeline engagement. With the deadline this close, most of the teams we speak to do not need a six-month migration programme — they have built the Graph code path and now need to land it safely, fast, without an outage. That is exactly the work this runbook describes, and exactly the work we deliver: instrumenting the dual-path build and feature flags, standing up the telemetry and alerts, defining the go/no-go gates and rollback triggers, and running the cutover and 72-hour hypercare alongside your team.

As a UK Office add-in development consultancy with deep experience across the unified manifest, nested app authentication and Microsoft Graph change notifications, we can join late, move quickly and de-risk your EWS to Microsoft Graph migration when the EWS deprecation October 2026 deadline leaves no room for a second attempt.

If you have under 90 days and an Outlook add-in still talking to EWS, get in touch for a short readiness review and a fixed-scope cutover plan. We would far rather help you go live calmly in September than firefight on 1 October.