--- title: WebhookSubscription - GraphQL Admin description: |- A webhook subscription is a persisted data object created by an app using the REST Admin API or GraphQL Admin API. It describes the topic that the app wants to receive, and a destination where Shopify should send webhooks of the specified topic. When an event for a given topic occurs, the webhook subscription sends a relevant payload to the destination. Learn more about the [webhooks system](https://shopify.dev/apps/webhooks). api_version: 2025-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription md: https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription.md --- # Webhook​Subscription object A webhook subscription is a persisted data object created by an app using the REST Admin API or GraphQL Admin API. It describes the topic that the app wants to receive, and a destination where Shopify should send webhooks of the specified topic. When an event for a given topic occurs, the webhook subscription sends a relevant payload to the destination. Learn more about the [webhooks system](https://shopify.dev/apps/webhooks). ## Fields * api​Version [Api​Version!](https://shopify.dev/docs/api/admin-graphql/latest/objects/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. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the webhook subscription was created. * filter [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) A constraint specified using search syntax that ensures only webhooks that match the specified filter are emitted. See our [guide on filters](https://shopify.dev/docs/apps/build/webhooks/customize/filters) for more details. * format [Webhook​Subscription​Format!](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionFormat) non-null The format in which the webhook subscription should send the data. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * include​Fields [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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](https://shopify.dev/docs/apps/build/webhooks/customize/modify_payloads). * legacy​Resource​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/UnsignedInt64) non-null The ID of the corresponding resource in the REST Admin API. * metafield​Namespaces [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The list of namespaces for any metafields that should be included in the webhook subscription. * metafields [\[Webhook​Subscription​Metafield​Identifier!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscriptionMetafieldIdentifier) non-null The list of identifiers specifying metafields to include in the webhook subscription. * topic [Webhook​Subscription​Topic!](https://shopify.dev/docs/api/admin-graphql/latest/enums/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. * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the webhook subscription was updated. * uri [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The URI to which the webhook subscription will send events. ### Deprecated fields * callback​Url [URL!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/URL) non-nullDeprecated * endpoint [Webhook​Subscription​Endpoint!](https://shopify.dev/docs/api/admin-graphql/latest/unions/WebhookSubscriptionEndpoint) non-nullDeprecated *** ## Map ### Fields and connections with this object * <->[WebhookSubscriptionConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/WebhookSubscriptionConnection#returns-nodes) * {}[WebhookSubscriptionEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscriptionEdge#field-WebhookSubscriptionEdge.fields.node) *** ## Queries * [webhook​Subscription](https://shopify.dev/docs/api/admin-graphql/latest/queries/webhookSubscription) 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). * [webhook​Subscriptions](https://shopify.dev/docs/api/admin-graphql/latest/queries/webhookSubscriptions) 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). *** ## \WebhookSubscription Queries ### Queried by * \[webhook​Subscription](https://shopify.dev/docs/api/admin-graphql/latest/queries/webhookSubscription) * \[webhook​Subscriptions](https://shopify.dev/docs/api/admin-graphql/latest/queries/webhookSubscriptions) *** ## Mutations * [webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionCreate) 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). * [webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionUpdate) 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). ### Deprecated mutations * [event​Bridge​Webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/eventBridgeWebhookSubscriptionCreate) mutation Deprecated * [event​Bridge​Webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/eventBridgeWebhookSubscriptionUpdate) mutation Deprecated * [pub​Sub​Webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/pubSubWebhookSubscriptionCreate) mutation Deprecated * [pub​Sub​Webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/pubSubWebhookSubscriptionUpdate) mutation Deprecated *** ## <\~> WebhookSubscription Mutations ### Mutated by * <\~>[webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionCreate) * <\~>[webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionUpdate) *** ## Interfaces * * [Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/LegacyInteroperability) interface * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## ||-WebhookSubscription Implements ### Implements * ||-[Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/LegacyInteroperability) * ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)