Updating webhook versions in Legacy Public App migrating to CLI

Webhooks and Events
1

I have a legacy public app that hasn’t yet been migrated to the CLI system. My app previously used the REST API to create webhook subscriptions on each store that installed the app. The webhook subscriptions’ API version was controlled via the Partner Dashboard app configuration screen.

I’m now upgrading my app to use API version 2025-01. I saw that the REST API no longer supported webhook subscription management, so I updated my app to use GraphQL for all webhook-related tasks. Then, I went to the Partner dashboard to update configuration there, but found that it is no longer possible to manage app config via the dashboard, and I must update my app to the CLI system.

I think I have a handle on migrating my app to use the CLI system. Since I don’t have any extensions, it seems pretty straight forward. But, what effects, if any, does this have on webhook subscriptions? I believe that I’ll now have to set my API and webhook event API versions in the toml config file, then deploy the updated app version. But, does this automatically affect the existing webhook subscriptions on each shop that were created via REST? It seems that there’s now a thing called app subscriptions that are different from the shop subscriptions that I’ve been creating. I’m not sure if I know enough yet to ask intelligent questions, but here are some that I currently have:

  1. Are app subscriptions applied to each shop that installs my app? Meaning, that in most cases you’d only use shop subscriptions if one-off webhooks were needed?
    1. If so, should I delete all existing shop subscriptions (about 8 per shop over thousands of shops) and then add app-level subscriptions?
  2. Does the toml webhooks api version config value affect shop subscriptions? Or only app subscriptions?
    1. If only app subscriptions, would I need to delete and re-create every shop subscription after my app version is deployed in order to get every subscription updated to use the new version?
  3. I can currently query (previously via REST, and now via GraphQL) to get a list of webhook subscriptions on a particular shop. If I switch from shop to app subscriptions, is there a way to query to see and verify the webhook subscriptions, including versions and endpoints, that apply to that shop, even if its an app subscription? Or do I just have to view my config file and assume that “its good”?
  4. More generally, are there any other caveats or changes in relation to webhooks that I should be aware of when migrating to a CLI app?

Thanks in advance for any help.

2

Hello :waving_hand: I hope I can clarify some doubts:

First of all, what you have now are individual subscriptions for your app-installed shops. What you’ll set up in the toml file are subscriptions for your app that will be automatically applied to all installed shops. We really discourage mixing both approaches, except during migration.

First question:
Once you deploy your toml subscriptions they’ll automatically be applied to each shop that installs your app.
If you delete all the existing subscriptions you created using REST and then add the toml ones, there’ll be a period of time when you won’t receive anything.
If you add the toml ones and later delete the REST/GQL ones, there’ll be a period of time when you’ll receive duplicates.
It all depends on your use case. If you can handle dups or prepare your app to temporarily discard them, with the second option no webhooks will be missed.

Second question:
It affects the subscriptions in the toml. But if you decided to mix both kinds of subscriptions, it would be the event payload version of your shop subscriptions too.
This is not usually a problem because there’re very few breaking changes in the payloads. You’ll possibly get more fields that you’d simply discard.

Third question:
Every time you deploy a version of your toml, you’ll get a link that will let you see in the Dev Dashboard what you’ve deployed. There’s a list of all your previous versions there. The latest one is what you’ll currently have active in production for all the shops that have your app installed.

Fourth question:
I tried to hint some possible issues above.
There’re some ideas in About webhooks to help you discard duplicates. Maybe using different reception endpoints could help

3

Thanks very much, @Paco-Shopify. That all aligns with what I was coming to understand, and it sheds further light on how to proceed. I’ll attempt to migrate to toml subscriptions to simply my code and workflow for the future.