M365 Archive
Message CenterMajor change

MC1442608Microsoft SharePoint Embedded: Update to driveItem.webUrl behavior

Summary

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.

More information

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

Compliance considerations

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