Microsoft 365 Message Center item MC1442608

MC1442608 - Microsoft SharePoint Embedded: Update to driveItem.webUrl behavior

Microsoft is updating SharePoint Embedded's driveItem.webUrl to return browser launch URLs instead of stable file locations. Use driveItemId for stable identifiers. Changes roll out from mid-August 2026, with a temporary opt-out until February 22, 2027. Review and update applications accordingly.

Message Center ID

MC1442608

Category

plan For Change

Severity

normal

Services

SharePoint Online

Tags

Feature update, User impact, Admin impact

Published

2026-07-29

Last updated

2026-07-29

Expires

2037-03-01

[What and why]We are updating the behavior of the Microsoft Graph driveItem.webUrl property for content stored in SharePoint Embedded.After this change, driveItem.webUrl will return the URL used to open a file in a browser rather than being treated as a stable file location or identifier. Depending on the file type and your SharePoint Embedded configuration, the returned URL may be:A Microsoft 365 web viewer URLA SharePoint Embedded PDF viewer URLA redirect URL generated from your configured urlTemplateA Microsoft help page URLThis update aligns driveItem.webUrl with its intended purpose as a browser launch URL. Applications that require a stable identifier for a file should use driveItemId, which remains the only unique and stable identifier for an item within a drive. The SharePoint Embedded documentation describes driveItem.webUrl as the URL used to launch supported files in Microsoft 365 experiences.[Rollout schedule]Targeted Release: Beginning in mid-August 2026General Availability (Worldwide): Beginning in mid-February 2027Temporary opt-out available until: August 17, 2026 Customers who opt out before August 17, 2026, will have an additional six months to transition to the new behavior.Temporary opt-out support ends February 22, 2027After February 22, 2027, all customers will receive the updated driveItem.webUrl behavior.[Impact on your organization]Who is affectedOrganizations that develop, manage, or use SharePoint Embedded applications that rely on driveItem.webUrl as a permanent file location, stable URL, or file identifierPlatforms and servicesSharePoint EmbeddedMicrosoft GraphMicrosoft 365 web viewersSharePoint Embedded PDF viewerWhat will happenAfter this change:Word, Excel, PowerPoint, and other supported Microsoft 365 file types will return a Microsoft 365 viewer URL.PDF files will return a SharePoint Embedded PDF viewer URL.Unsupported file types with a configured urlTemplate will return a redirect URL generated from that template.Unsupported file types without a configured urlTemplate will return a Microsoft help page URL.Applications are not expected to require changes if driveItem.webUrl is used only to open files in a browser.Your application may require updates if it:Stores driveItem.webUrl as a permanent file location.Uses driveItem.webUrl as a file identifier.Compares driveItem.webUrl values over time to determine file identity or location.Passes driveItem.webUrl to services that require a stable storage URL.Assumes driveItem.webUrl remains unchanged across file types, viewer support scenarios, or redirect configurations.[Action required and recommendations]Review how your SharePoint Embedded applications use driveItem.webUrl.No action is required if driveItem.webUrl is used only to open files in a browser.We recommend:Identify any application dependencies on driveItem.webUrl as a stable identifier or permanent URL.Update applications to use driveItemId when a stable item identifier is required.Review redirect behavior for unsupported file types.Configure urlTemplate if users should be redirected back to your application. Review: Configure redirect behaviorValidate application behavior against the updated driveItem.webUrl experience before enforcement begins.Remove dependencies on the legacy driveItem.webUrl behavior before temporary opt-out support ends.Use driveItem.webUrl​ when your application needs a URL that opens the file in a browser. Use the driveItemId​ when you need a stable, unique reference to an item.Organizations that need additional migration time can temporarily retain the current behavior for a SharePoint Embedded container type by setting UseLegacyItemWebUrl to true. Review: Set-SPOContainerTypeConfiguration The temporary opt-out is intended only as a migration aid and will no longer be honored after February 22, 2027.Learn moreConfigure redirect behavior - Open Office files from your app | SharePoint | Microsoft LearnSet-SPOContainerTypeConfiguration | Microsoft.OnlineSharePoint.PowerShell | PowerShell | Microsoft Learn[Compliance considerations]No compliance considerations identified. Review as appropriate for your organization.