Like the majority of Shopify’s APIs, webhooks are [versioned](/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](/docs/apps/build/webhooks) work.

- You're familiar with the webhooks [best practices](/docs/apps/build/webhooks/best-practices).

- You're [authenticated](/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](/docs/api/shopify-cli/app/app-webhook-trigger)
[CLI](/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.

      <p>
        <div class="react-code-block" data-preset="basic">
        <div class="react-code-block-preload ThemeMode-dim">
        <div class="react-code-block-preload-bar basic-codeblock"></div>
        <div class="react-code-block-preload-placeholder-container">
        <div class="react-code-block-preload-code-container">
        <div class="react-code-block-preload-codeline-number"></div>
        <div class="react-code-block-preload-codeline"></div>
        </div>

        </div>
        </div>

        <script data-option="title" data-value=""></script>

        <script type="text/plain" data-language="shell">
        shopify app webhook trigger --api-version=<new-version-handle> --address=<destination> --topic=<topic-name>
        </script>

        </div>
        </p>


## 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](/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions) of your app.

If your app was created with Shopify CLI, and you're using [Shopify CLI version 3.63.0 or higher](https://www.npmjs.com/package/@shopify/cli), 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](https://partners.shopify.com/organizations).

### Select the newer 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`](/docs/apps/build/cli-for-apps/app-configuration#webhooks).

1. Deploy a new version of your app by running `shopify app deploy`.

### Select the newer API version in the Partner Dashboard

1. From your [Partner Dashboard](https://partners.shopify.com/organizations), go to **Apps**.

2. Click the app that you want to update.

3. Click **Configuration**.

4. In the **Event version** section, from the  **Event version** drop-down list, select an API version.

5. Click **Save and 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](/docs/apps/build/webhooks/troubleshooting-webhooks), track failed deliveries, and fix issues.