Microsoft SharePoint Embedded: Update to driveItem.webUrl behavior
- Jul 29
- 3 min read
MC1442608
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.
Compliance considerations
No compliance considerations identified. Review as appropriate for your organization.
