--- title: Use a newer API version description: Learn how to manage webhook API versions in your app. source_url: html: 'https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version' md: >- https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#requirements) * [Step 1: Update your code](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-1-update-your-code) * [Step 2: Test the newer API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-2-test-the-newer-api-version) * [Step 3: Select the newer API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-3-select-the-newer-api-version) * [Step 4: Remove references to the earlier API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-4-remove-references-to-the-earlier-api-version) * [Next steps](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#next-steps) # Use a newer API version Like the majority of Shopify’s APIs, webhooks are [versioned](https://shopify.dev/docs/api/usage/versioning). 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 * You're familiar with how [webhooks](https://shopify.dev/docs/apps/build/webhooks) work. * You're familiar with the webhooks [best practices](https://shopify.dev/docs/apps/build/webhooks/best-practices). * You're [authenticated](https://shopify.dev/docs/apps/build/authentication-authorization) with the GraphQL Admin API. *** ## 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 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](https://shopify.dev/docs/api/shopify-cli/app/app-webhook-trigger) [CLI](https://shopify.dev/docs/api/shopify-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. ```shell shopify app webhook trigger --api-version= --address= --topic= ``` *** ## 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](https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions) of your app. ### Update 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`](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#webhooks). 2. Save your configuration file. If `app dev` is running, the webhook API version will be updated automatically for your dev 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`. ### Update the API version in the Dev Dashboard You can also update the webhook API version through the Dev Dashboard: 1. From your [Dev Dashboard](https://dev.shopify.com/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**. *** ## 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 * View a report of your app’s [webhook deliveries](https://shopify.dev/docs/apps/build/webhooks/troubleshooting-webhooks), track failed deliveries, and fix issues. *** * [Requirements](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#requirements) * [Step 1: Update your code](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-1-update-your-code) * [Step 2: Test the newer API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-2-test-the-newer-api-version) * [Step 3: Select the newer API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-3-select-the-newer-api-version) * [Step 4: Remove references to the earlier API version](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#step-4-remove-references-to-the-earlier-api-version) * [Next steps](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version.md#next-steps)