Webhooks not firing ("themes/update" and "themes/publish")

Webhooks and Events
1

Hey,
I have an app configured with the following webhooks entry in shopify.app.toml

webhooks]
api_version = "2025-07"

[[webhooks.subscriptions]]
uri = "/webhooks/compliance"
compliance_topics = [
  "customers/data_request",
  "customers/redact",
  "shop/redact",
]

[[webhooks.subscriptions]]
topics = [
  "app_subscriptions/update",
  "app/scopes_update",
  "app/uninstalled",
  "products/create",
  "products/delete",
  "products/update",
  "shop/update",
  "themes/update",
  "themes/publish",
]
uri = "/webhooks"

So far, when testing my app, I could see all of the webhooks working properly except themes/update and themes/publish

My goal is to provide my users with some information about their onboarding state.
I wanted to use themes/update to get notified when the user made a change to his theme and check if he added my app block.
Similarly, I want to use themes/publish to know when the theme with my app block is published and live.

I am not sure if this isnā€™t working because it is a test store or if there is anything else wrong with this.

Any help would be appreciated.

Thanks

2

Have you got access to the themes scope?

Also FYI, themes/update is not fired when theme files are updated, so it probably wonā€™t be of any use to you.

3

Hey Luke, thanks for your help :slight_smile:

Yeah, I have the following access scopes

[access_scopes]
scopes = "read_inventory,read_products,read_themes"

I think read_themes should do the trick right?

Actually, if I understand it correctly, this access_scope should grant me permission to read the theme - but is it also related to the webhook subscription?

4

By the way, if you just want to check whether the user has added your block or enabled the app embed, you can do that by reading the theme files. For example, to see if the embed is ON, you can look into config/settings_data.json and check if your app embed is present in the JSON. Similarly, to know if your app block is added on the product template, you can read templates/product.json and verify it there.

You will need read_themes access scopes to read theme files and can use this graphql query theme - GraphQL Admin

5

Hey, thanks @Gulam_Hussain_Quinn
The thing is that I would not know ā€œwhenā€ to check if the embed exists and enabled.

I wanted to use the webhook as a trigger for that check :folded_hands:

6

Are you planning to notify them like ā€˜hey, the app embed just went liveā€™? Just curious what the use case is for knowing the exact ā€œwhenā€?

7

@Gulam_Hussain_Quinn Sure :slight_smile:

For context:
I am building a chat assistant so the user has to add the block to his site in order for the app to be useable.

I have an onboarding experience where I guide the user through the things he needs to do to get the best experience and one of the steps is to add the chat widget.

I have a deep link into the theme editor that adds and enables the block but the user still needs to save and publish his store in order for the app to work.

Currently I donā€™t have any way of knowing ā€œwhenā€ is a good time to check if the user added the block

8

This is how I do it, and many other apps do the same. In the onboarding process, I have a button that sends the user to a deep link in a new tab. When the user clicks the link, I add ?activationprogress=true to the current URL. The user goes to the new tab, saves the changes there, and then comes back to the app tab. When they return, I check if the tab is visible(by listing to visibility event ) and if the URL has activationprogress=true. If yes, I make an API call to check if the user saved the changes by looking at config/settings_data.json or another related file. You can also add another button for the user to click, like ā€œre-checkā€ or ā€œvalidate,ā€ to make things easier.

Also, i donā€™t think theme/update triggers when theme files changes (not sure please confirm this), it only triggers when new theme goes live or theme name changes.

9

Also, i donā€™t think theme/update triggers when theme files changes (not sure please confirm this), it only triggers when new theme goes live or theme name changes.

Oh! Thanks! had no idea - I assumed it fires on ā€œsaveā€ and ā€œpublishā€ :sweat_smile:

I will take your advice and check the status when the user returns to the tab.
Thank you

10

For reference this is what the shopify docs AI assistant had to say:

Question:

please explain the use cases of ā€œthemes/updateā€ and ā€œthemes/publishā€ webhooks. what are they used for. when exactly do they fire.

Answer:

Hereā€™s an explanation of the use cases and firing conditions for the Shopify webhooks ā€œthemes/updateā€ and ā€œthemes/publishā€:

1. themes/update Webhook

Use Case:
The themes/update webhook is used to notify your app whenever a theme in a Shopify store is updated. This includes changes to the themeā€™s code, settings, or assets. Apps that need to keep an external system in sync with the current state of a storeā€™s themes, or that want to trigger actions (such as re-indexing, cache invalidation, or sending notifications) when a theme is modified, should subscribe to this webhook.

When does it fire?

  • Whenever a themeā€™s code, settings, or assets are changed.
  • This can happen through the Shopify admin (using the code editor or theme editor), via the API, or through integrations like the Shopify GitHub app.
  • It does not fire when a theme is published (thatā€™s handled by themes/publish).

Typical scenarios:

  • A merchant or developer edits theme files (e.g., Liquid, CSS, JS).
  • Theme settings are changed (e.g., color, layout, or section configuration).
  • An app or integration programmatically updates theme assets.

2. themes/publish Webhook

Use Case:
The themes/publish webhook notifies your app when a theme is published (i.e., made the live theme on the storefront). This is useful for apps that need to react when the storefrontā€™s appearance changes, such as analytics, personalization, or theme management tools.

When does it fire?

  • When a merchant selects a theme from their theme library and publishes it, making it the active theme for their online store.
  • This can be triggered via the Shopify admin, API, or integrations.

Typical scenarios:

  • A merchant publishes a new theme to replace the current live theme.
  • An app programmatically publishes a theme (e.g., after a successful deployment or update).

Summary Table

Webhook Fires Whenā€¦ Use Cases
themes/update Any change to a themeā€™s code, settings, or assets Syncing theme state, cache invalidation, notifications
themes/publish A theme is made the live storefront theme Reacting to storefront changes, analytics, theme management

Note:

  • These webhooks are essential for apps that need to track theme changes or react to theme publishing events.
  • They do not provide the same payloads: themes/update gives details about the updated theme, while themes/publish indicates which theme is now live.
11

No, I mean please check yourself by subscribing to the themes/update webhook and then change something in the theme to see if it fires. Donā€™t just take my word for it, because I tested this 1-2 years ago and at that time themes/update didnā€™t fire when theme code changed. Maybe they added support for code changes as well, so please subscribe and see if this works. I donā€™t want to give you wrong information.

1 Like