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.
- 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
- 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.
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
- From your Partner Dashboard, go to Apps.
- Click the app that you want to update.
- Click App setup.
- In the Event subscriptions section, select an API version from the Event 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.
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.
- Consult the GraphQL Admin API or REST Admin API reference for the complete list of supported webhook topics.
- Set up the mandatory webhooks that your app requires.
- View a report of your app’s webhook deliveries, track failed deliveries, and fix issues before they affect merchants.
- Manage large volumes of event notifications by integrating your app with Amazon EventBridge or Google Cloud Pub/Sub.