Skip to main content

Use a newer API version

Like the majority of Shopify’s APIs, webhooks are versioned. We strongly recommend updating your apps to use the latest stable API version every quarter.

This tutorial shows you how to manage webhook API versions in your app.

Anchor to RequirementsRequirements

Anchor to Step 1: Update your codeStep 1: Update your code

If the new version requires webhooks to be handled differently, then you need to update your code.

Add logic to your code so that it handles webhooks differently depending on their API versions. To check the API version, your app can use the X-Shopify-Api-Version request header in every webhook POST request. When you're using Google Cloud Pub/Sub or Amazon EventBridge for delivery of your webhooks, then you receive this information as part of the message payload instead.

Anchor to Step 2: Test the newer API versionStep 2: Test the newer API version

Before you select a newer webhook API version, you need to test it against your code.

Your existing webhook subscriptions will continue to use the earlier API version. Before you make the change, we recommend you to use the app webhook trigger CLI command.

You can pass no parameters and follow the command prompts, but setting a fixed --api-version to the new version and --address to a location of your choice, will help you streamline the testing process for each topic you consume.

shopify app webhook trigger --api-version=<new-version-handle> --address=<destination> --topic=<topic-name>

Anchor to Step 3: Select the newer API versionStep 3: Select the newer API version

Select the newer API version for your app. This affects all shop-specific and app-specific webhook subscriptions of your app.

Anchor to Update the API version in your app configuration fileUpdate the API version in your app configuration file

  1. In your app configuration file, set webhooks.api_version to the latest stable version. Learn more about api_version.

  2. Save your configuration file. If app dev is running, the webhook API version will be updated automatically for your development store.

  3. When you're ready to release the API version update to production, deploy a new version of your app by running shopify app deploy.

Anchor to Update the API version in the Dev DashboardUpdate the API version in the Dev Dashboard

You can also update the webhook API version through the Dev Dashboard:

  1. From your Dev Dashboard, go to Apps.

  2. Click on your app.

  3. Click Versions → Create a version.

  4. In the Webhooks API Version field, select the newer API version.

  5. Click Release.

Anchor to Step 4: Remove references to the earlier API versionStep 4: Remove references to the earlier API version

Make sure that your code handles the updated webhook payloads correctly. After you've verified that everything is working, update your code to remove the following:

  • The logic specific to the earlier webhook API version

  • References to the earlier webhook API version

    Also remove the webhooks you've created in step 2 from the Shopify admin.

Anchor to Next stepsNext steps

  • View a report of your app’s webhook deliveries, track failed deliveries, and fix issues.
Was this page helpful?