Skip to main content

Upgrading From 3.22 To 3.23

info

To follow a zero-downtime upgrade strategy to 3.23, we recommend first migrating to the latest 3.22.x release and enabling the Celery worker to process all data migrations asynchronously. Otherwise, you will need to schedule downtime to ensure data migrations complete correctly.

Changes in Webhook Emission for Instance Updates​

A new setting, useLegacyUpdateWebhookEmission, has been introduced in shop settings to control the behavior of update webhook emissions. This setting allows users to toggle between the legacy behavior (sending both update webhooks and metadata-specific webhooks for metadata-only changes) and the new behavior (sending only metadata-specific webhooks instead). The legacy behavior is now deprecated as of version 3.22 and will be removed in future versions. The new flow will become the default behavior.

Description​

  • When enabled - legacy behavior: Both update webhooks (e.g., customerUpdated, productVariantUpdated) and metadata-specific webhooks (e.g., customerMetadataUpdated, productVariantMetadataUpdated) are sent for metadata-only changes.
  • When disabled - new behavior: Only metadata-specific webhooks (e.g., customerMetadataUpdated, productVariantMetadataUpdated) are sent for metadata-only changes, and update webhooks are not triggered.

Benefits of Disabling​

Disabling this setting prevents sending update webhooks when only metadata changes are made to the instance, reducing unnecessary webhook traffic.

Applicable Mutations​

This setting applies to all mutations capable of triggering both <object>Updated and <object>MetadataUpdated webhooks.

Dashboard extensions​

Since 3.22, Dashboard extension manifests are validated on the frontend. Installing apps directly via GraphQL is discouraged, as such apps may not work properly.

For Cloud users: You should not be affected by these changes.

For self-hosted:

  • Ensure you use the latest matching Dashboard versions. Early Dashboard v3.22.x releases are not compatible with later Core 3.22 versions. Dashboard v3.23.x and Core v3.23.x are fully compatible.
  • Fields on type AppExtension and AppExtensionManifest: mount, target, and options have been removed. Use the fields mountName, targetName, and settings instead, which directly replace the old ones.
  • New fields are intended to be used by Dashboard only. Modifying them requires caution and may require frontend adjustments.
  • New fields are no longer strictly validated, which means installing an app extension without Dashboard can cause unexpected Dashboard behavior.