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.

Requirements

Anchor link to section titled "Requirements"

You're familiar with how webhooks work.
You're familiar with the webhooks best practices.
You're authenticated with the GraphQL Admin API.

Step 1: Update your code

Anchor link to section titled "Step 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.

Step 2: Test the newer API version

Anchor link to section titled "Step 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.

Step 3: Select the newer API version

Anchor link to section titled "Step 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.

If your app was created with Shopify CLI, and you're using Shopify CLI version 3.63.0 or higher, then we recommend that you select the newer API version in your app configuration file. Otherwise, select the newer webhook API version for a public or custom app in the Partner Dashboard.

Select the newer API version in your app configuration file

Anchor link to section titled "Select the newer API version in your app configuration file"

In your app configuration file, set webhooks.api_version to the latest stable version. Learn more about api_version.
Deploy a new version of your app by running shopify app deploy.

Select the newer API version in the Partner Dashboard

Anchor link to section titled "Select the newer API version in the Partner Dashboard"

From your Partner Dashboard, go to Apps.
Click the app that you want to update.
Click Configuration.
In the Event version section, from the Event version drop-down list, select an API version.
Click Save and release.

Step 4: Remove references to the earlier API version

Anchor link to section titled "Step 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.

Next steps

Anchor link to section titled "Next steps"

View a report of your app’s webhook deliveries, track failed deliveries, and fix issues.