Skip to main content
Anchor to WebhookSubscription

WebhookSubscription

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.

Anchor to FieldsFields

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.

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.

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 metafieldsmetafields
•[WebhookSubscriptionMetafieldIdentifier!]!
non-null

The list of identifiers specifying metafields to include 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.

Anchor to updatedAtupdatedAt
•DateTime!
non-null

The date and time when the webhook subscription was updated.

Anchor to uriuri
•String!
non-null

The URI to which the webhook subscription will send events.

Deprecated fields

Anchor to callbackUrlcallbackUrl
•URL!
non-nullDeprecated
Anchor to endpointendpoint
•WebhookSubscriptionEndpoint!
non-nullDeprecated
Was this section helpful?

Anchor to QueriesQueries

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.

Anchor to webhookSubscriptionswebhookSubscriptions
•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.

Was this section helpful?

Anchor to MutationsMutations

Anchor to webhookSubscriptionCreatewebhookSubscriptionCreate
•mutation

Creates a webhook subscription that notifies your 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 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 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.

Anchor to webhookSubscriptionUpdatewebhookSubscriptionUpdate
•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 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.

Deprecated mutations

Anchor to eventBridgeWebhookSubscriptionCreateeventBridgeWebhookSubscriptionCreate
•mutation
Deprecated
Anchor to eventBridgeWebhookSubscriptionUpdateeventBridgeWebhookSubscriptionUpdate
•mutation
Deprecated
Anchor to pubSubWebhookSubscriptionCreatepubSubWebhookSubscriptionCreate
•mutation
Deprecated
Anchor to pubSubWebhookSubscriptionUpdatepubSubWebhookSubscriptionUpdate
•mutation
Deprecated
Was this section helpful?

Anchor to InterfacesInterfaces

Was this section helpful?