--- 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-01 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/2025-01/objects/webhooksubscription md: https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/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/2025-01/scalars/DateTime) non-null The date and time when the webhook subscription was created. * filter [String](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/enums/WebhookSubscriptionFormat) non-null The format in which the webhook subscription should send the data. * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) non-null A globally-unique ID. * include​Fields [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/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/2025-01/scalars/String) non-null The list of namespaces for any metafields that should be included in the webhook subscription. * topic [Webhook​Subscription​Topic!](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/scalars/DateTime) non-null The date and time when the webhook subscription was updated. ### Deprecated fields * callback​Url [URL!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/URL) non-nullDeprecated * endpoint [Webhook​Subscription​Endpoint!](https://shopify.dev/docs/api/admin-graphql/2025-01/unions/WebhookSubscriptionEndpoint) non-nullDeprecated *** ## Map ### Fields and connections with this object * <->[WebhookSubscriptionConnection.nodes](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/WebhookSubscriptionConnection#returns-nodes) * {}[WebhookSubscriptionEdge.node](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/WebhookSubscriptionEdge#field-WebhookSubscriptionEdge.fields.node) *** ## Queries * [webhook​Subscription](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/queries/webhookSubscriptions) query Retrieves a paginated list of webhook subscriptions created using the API for the current app and shop. *** Note Returns only shop-scoped subscriptions, not app-scoped subscriptions configured in TOML files. *** Subscription details include event topics, endpoint URIs, filtering rules, field inclusion settings, and metafield namespace permissions. Results support cursor-based pagination that you can filter by topic, format, or custom search criteria. 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/2025-01/queries/webhookSubscription) * \[webhook​Subscriptions](https://shopify.dev/docs/api/admin-graphql/2025-01/queries/webhookSubscriptions) *** ## Mutations * [webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/webhookSubscriptionCreate) mutation Creates a webhook subscription that notifies your [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) when specific events occur in a shop. Webhooks push event data to your endpoint immediately when changes happen, eliminating the need for polling. The subscription configuration supports multiple endpoint types including HTTPS URLs, Google Pub/Sub topics, and AWS EventBridge event sources. You can filter events using [Shopify API search syntax](https://shopify.dev/docs/api/usage/search-syntax) to receive only relevant webhooks, control which data fields are included in webhook payloads, and specify metafield namespaces to include. *** Note The Webhooks API version [configured in your app](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version) determines the API version for webhook events. You can't specify it per subscription. *** 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/2025-01/mutations/webhookSubscriptionUpdate) mutation Updates a webhook subscription's configuration. Modify the endpoint URL, event filters, included fields, or metafield namespaces without recreating the subscription. The mutation accepts a [`WebhookSubscriptionInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/WebhookSubscriptionInput) that specifies the new configuration. You can switch between endpoint types (HTTP, Pub/Sub, EventBridge) by providing a different URI format. Updates apply atomically without interrupting webhook delivery. 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/2025-01/mutations/eventBridgeWebhookSubscriptionCreate) mutation Deprecated * [event​Bridge​Webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/eventBridgeWebhookSubscriptionUpdate) mutation Deprecated * [pub​Sub​Webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/pubSubWebhookSubscriptionCreate) mutation Deprecated * [pub​Sub​Webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/pubSubWebhookSubscriptionUpdate) mutation Deprecated *** ## <\~> WebhookSubscription Mutations ### Mutated by * <\~>[webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/webhookSubscriptionCreate) * <\~>[webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/webhookSubscriptionUpdate) *** ## Interfaces * * [Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/LegacyInteroperability) interface * [Node](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/Node) interface *** ## ||-WebhookSubscription Implements ### Implements * ||-[Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/LegacyInteroperability) * ||-[Node](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/Node)