We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Versioned webhooks

Webhook payloads can change between API versions, similar to API response payloads. You can select the API version that you want to use for webhooks, and that version will be used for all webhooks that are sent to your app.

When your selected API version becomes unsupported, Shopify falls forward to using the next supported stable version. Webhooks include the X-Shopify-Api-Version request header to indicate the API version that was used to generate the webhook. If this value is different than the version that you selected, then your selected API version is no longer supported.

When your app is affected by the webhook changes in a newer API version, you should update your app before support for your selected API version is removed.

Select a webhook API version for a public 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 Webhooks section, select an API version from the Webhook API 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.

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.

Update your app to use a newer webhook API version

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

Step 1: Update your code

Add logic to your code so that your app 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 development store's notification settings, add some webhooks that use the newer version, and then send some test payloads. Webhooks created from your app continue to use the older API version.

Check that your app correctly handles the test webhooks, and make any necessary adjustments to your code.

Step 3: Select the newer API version

Select the newer API version for your public or private app. All webhooks sent to your app will now use this version.

Step 4: Test that webhooks are working

Test that your app handles webhooks correctly.

Step 5: Remove references to the older API version

Update your code to remove the logic that you added, and all the references to the old webhook API version.

Sign up for a Partner account to get started.

Sign up