Document webhook reconciliation behavior in shopify-app-express#3158
Merged
joshwheeler merged 3 commits intomainfrom Apr 15, 2026
Merged
Document webhook reconciliation behavior in shopify-app-express#3158joshwheeler merged 3 commits intomainfrom
joshwheeler merged 3 commits intomainfrom
Conversation
joshwheeler
force-pushed
the
docs/webhook-reconciliation-warning
branch
2 times, most recently
from
adfefb7 to
0e7ffd4
Compare
The express package docs previously presented shop-specific webhooks (managed via the GraphQL Admin API) as the only option without mentioning app-specific subscriptions. App-specific subscriptions, configured in shopify.app.toml, are Shopify's recommended approach for most apps since Shopify manages the subscription lifecycle automatically. Changes across all express package docs: - README: Reframe "Webhook registration" as broader "Webhooks" section that introduces both subscription types, links to Shopify's comparison docs, and scopes the reconciliation warning to shop-specific subscriptions only - processWebhooks.md: Label webhookHandlers as shop-specific in the description, parameters, and example; note that the middleware is still needed for HTTP delivery with app-specific subscriptions - shopifyApp.md: Clarify that webhooks.path applies to both subscription types and that processWebhooks defines shop-specific subscriptions - Migration guide: Add tip about switching to app-specific subscriptions during migration, label code examples as shop-specific Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
byrichardpowell
force-pushed
the
docs/webhook-reconciliation-warning
branch
from
4e8e464 to
7ec4d41
Compare
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Thanks @joshwheeler I've pushed some updates:
If yu are comfortable with these changes please merge 👍 |
byrichardpowell
approved these changes
Apr 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README does not document that when
auth.callback()completes an offline OAuth session, it automatically callsregister(), which deletes any webhook subscriptions not declared inwebhookHandlers.Added a Webhook registration section explaining this behavior and a migration warning for apps moving from custom implementations.