WebhookSubscription

Anchor to apiVersionapiVersion

•ApiVersion!

non-null

The Admin API version that Shopify uses to serialize webhook events. This value is inherited from the app that created the webhook subscription.

Show fields

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time when the webhook subscription was created.

Anchor to filterfilter

•String

A constraint specified using search syntax that ensures only webhooks that match the specified filter are emitted. See our guide on filters for more details.

Anchor to formatformat

•WebhookSubscriptionFormat!

non-null

The format in which the webhook subscription should send the data.

Show enum values

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to includeFieldsincludeFields

•[String!]!

non-null

The list of fields to be included in the webhook subscription. Only the fields specified will be included in the webhook payload. If null, then all fields will be included. Learn more about modifying webhook payloads.

Anchor to legacyResourceIdlegacyResourceId

•UnsignedInt64!

non-null

The ID of the corresponding resource in the REST Admin API.

Anchor to metafieldNamespacesmetafieldNamespaces

•[String!]!

non-null

The list of namespaces for any metafields that should be included in the webhook subscription.

Anchor to topictopic

•WebhookSubscriptionTopic!

non-null

The type of event that triggers the webhook. The topic determines when the webhook subscription sends a webhook, as well as what class of data object that webhook contains.

Show enum values

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time when the webhook subscription was updated.

Deprecated fields

Anchor to callbackUrlcallbackUrl

•URL!

non-nullDeprecated

Anchor to endpointendpoint

•WebhookSubscriptionEndpoint!

non-nullDeprecated

Show union types

Anchor to webhookSubscriptionwebhookSubscription

•query

Returns a webhook subscription by ID.

Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.

Show fields

Anchor to webhookSubscriptionswebhookSubscriptions

•query

Retrieves a paginated list of shop-scoped webhook subscriptions configured for the current app. This query returns webhook subscriptions created via the API for this shop, not including app-scoped subscriptions configured via TOML files.

For example, an app dashboard might use this query to display all configured webhooks, showing which events trigger notifications and their delivery endpoints for troubleshooting integration issues.

Use the webhookSubscriptions query to:

• Audit all active shop-scoped webhook configurations
• View and manage webhook subscription configurations
• Display subscription details in app dashboards
• Retrieve existing webhook configurations for dynamic integration setups
• Check which subscriptions already exist before creating new ones

The query returns comprehensive subscription data including event topics, endpoint configurations, filtering rules, API versions, and metafield namespace permissions. Each subscription includes creation and modification timestamps for tracking configuration changes.

Results support standard GraphQL pagination patterns with cursor-based navigation, allowing efficient retrieval of large webhook subscription lists. The response includes detailed endpoint information varying by type - HTTP callback URLs, EventBridge ARNs, or Pub/Sub project and topic specifications.

Advanced subscription features like event filtering using Shopify search syntax, field inclusion rules, and metafield namespace access are fully exposed, providing complete visibility into webhook configuration.

Learn more about webhook subscription queries.

Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.

Show fields

Anchor to webhookSubscriptionCreatewebhookSubscriptionCreate

•mutation

Set up webhook subscriptions so your app gets notified instantly when things happen in a merchant's store. Instead of constantly checking for changes, webhooks push updates to your app the moment they occur, making integrations faster and more efficient.

For example, an inventory management app might create subscriptions for orders/paid and inventory_levels/update events to automatically adjust stock levels and trigger fulfillment processes when customers complete purchases.

Use webhookSubscriptionCreate to:

• Set up real-time event notifications for your app
• Configure specific topics like order creation, product updates, or customer changes
• Define endpoint destinations (HTTPS, EventBridge, or Pub/Sub)
• Filter events using Shopify search syntax to receive notifications only for relevant events
• Configure field inclusion to control which data fields are included in webhook payloads

The mutation supports multiple endpoint types and advanced filtering options, allowing you to create precisely targeted webhook subscriptions that match your app's integration needs. The API version is inherited from the app configuration and cannot be specified per subscription. Filters use Shopify search syntax to determine which events trigger notifications.

Successful creation returns the webhook subscription fields that you request in your query. The mutation validates topic availability, filter syntax, and endpoint configuration.

Learn more about creating webhook subscriptions.

Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.

Show payload

Anchor to webhookSubscriptionUpdatewebhookSubscriptionUpdate

•mutation

Updates an existing webhook subscription's configuration, allowing you to modify endpoints, topics, filters, and other subscription settings without recreating the entire subscription. This mutation provides flexible webhook management for evolving app requirements.

For example, when migrating from HTTP endpoints to EventBridge, you can update the subscription's endpoint configuration while preserving the same topic subscriptions and filters, ensuring continuity of event delivery during infrastructure changes.

Use webhookSubscriptionUpdate to:

• Change webhook endpoint URLs or destination types
• Modify event filtering criteria to refine event relevance
• Adjust field inclusion settings to optimize payload sizes
• Configure metafield namespace access for extended data

The mutation supports comprehensive configuration changes including endpoint type switching (HTTP to Pub/Sub, for instance), topic modifications, and advanced filtering updates. The API version is inherited from the app configuration and cannot be changed per subscription.

Updates are applied atomically, ensuring that webhook delivery continues uninterrupted during configuration changes. The response includes the updated subscription fields that you request in your query, and validation errors if requested.

Learn more about updating webhook configurations.

Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.

Show payload

Deprecated mutations

Anchor to eventBridgeWebhookSubscriptionCreateeventBridgeWebhookSubscriptionCreate

•mutation

Deprecated

Show payload

Anchor to eventBridgeWebhookSubscriptionUpdateeventBridgeWebhookSubscriptionUpdate

•mutation

Deprecated

Show payload

Anchor to pubSubWebhookSubscriptionCreatepubSubWebhookSubscriptionCreate

•mutation

Deprecated

Show payload

Anchor to pubSubWebhookSubscriptionUpdatepubSubWebhookSubscriptionUpdate

•mutation

Deprecated

Show payload

Anchor to LegacyInteroperabilityLegacyInteroperability

•interface

Anchor to NodeNode

•interface