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
- From your Partner Dashboard, go to Apps.
- Click the app that you want to update.
- Click App setup.
- In the Webhooks section, select an API version from the Webhook API version drop-down-list.
- Click Save.
Select a webhook API version for a private app
- From the Shopify admin, go to Apps.
- Click Manage private apps.
- Click the private app that you're updating.
- In the Admin API section, select an API version from the Webhook API version drop-down list.
- Click Save.
Select a webhook API version for Shopify admin notifications
- From the Shopify admin, go to Settings > Notifications.
- Click Create webhook, or click an existing webhook.
- If this is a new webhook, then enter the event, format, and URL.
- Select an API version from the Webhook API version drop-down list.
- 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
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.