Managing webhook API versions

Like the majority of Shopify’s APIs, webhook resources are versioned. Make sure your code is updated regularly to use a supported webhook version.

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

Requirements

  • You're familiar with how webhooks work.
  • You're authenticated with the GraphQL Admin API or REST Admin API.

Step 1: Update your code

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

Add logic to your code so that it handles webhooks differently depending on their API version. To check the API version, your app can use the X-Shopify-Api-Version request header in every webhook POST request.

Step 2: Test the newer API version

From your store's notification settings, add some webhooks that use the newer version, and then send some test payloads. Your existing webhooks will continue to use the older API version. Check that your code correctly handles the test webhooks, and make any necessary adjustments.

Select a webhook API version for Shopify admin notifications

  1. From the Shopify admin, go to Settings > Notifications.
  2. Click Create webhook, or click an existing webhook.
  3. If this is a new webhook, then enter the event, format, and URL.
  4. Select an API version from the Webhook API version drop-down list.
  5. Click Save webhook.

Step 3: Select the newer API version

Select the newer API version for your public, custom, or private app. Your updated webhook will now use this version.

Select a webhook API version for a public or custom app

  1. From your Partner Dashboard, go to Apps.
  2. Click the app that you want to update.
  3. Click App setup.
  4. In the Event subscriptions section, select an API version from the Event version drop-down list.
  5. Click Save.

Select a webhook API version for a private app

  1. From the Shopify admin, go to Apps.
  2. Click Manage private apps.
  3. Click the private app that you're updating.
  4. In the Admin API section, select an API version from the Webhook API version drop-down list.
  5. Click Save.

Step 4: Test webhooks and remove references to the older 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 logic that you added and all the references to the old webhook API version.

Next steps