Microsoft SharePoint Embedded: Update to driveItem.webUrl behavior

[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 URL
• A SharePoint Embedded PDF viewer URL
• A redirect URL generated from your configured urlTemplate
• A Microsoft help page URL

This 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 2026
• General Availability (Worldwide): Beginning in mid-February 2027
• Temporary 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, 2027
• After February 22, 2027, all customers will receive the updated driveItem.webUrl behavior.

[Impact on your organization]

Who is affected

Organizations that develop, manage, or use SharePoint Embedded applications that rely on driveItem.webUrl as a permanent file location, stable URL, or file identifier

Platforms and services

• SharePoint Embedded
• Microsoft Graph
• Microsoft 365 web viewers
• SharePoint Embedded PDF viewer

What will happen

After 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 behavior
• Validate 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 more

• Configure redirect behavior - Open Office files from your app | SharePoint | Microsoft Learn
• Set-SPOContainerTypeConfiguration | Microsoft.OnlineSharePoint.PowerShell | PowerShell | Microsoft Learn

[Compliance considerations]

No compliance considerations identified. Review as appropriate for your organization.