Choose a version:

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 webhookSubscription 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.

Anchor to idid •ID! required: The ID of the WebhookSubscription to return.

Anchor to webhookSubscriptions 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.

Arguments

Anchor to firstfirst

•Int

The first n elements from the paginated list.

Anchor to afterafter

•String

The elements that come after the specified cursor.

Anchor to lastlast

•Int

The last n elements from the paginated list.

Anchor to beforebefore

•String

The elements that come before the specified cursor.

Anchor to reversereverse

•Boolean

Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey

•WebhookSubscriptionSortKeys

Default:CREATED_AT

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to queryquery

•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to created_at •time
Anchor to id •id: Filter by id range.
Anchor to updated_at •time

Anchor to callbackUrlcallbackUrl

•URL

Deprecated

Anchor to uriuri

•String

URI to filter by. Supports an HTTPS URL, a Google Pub/Sub URI (pubsub://{project-id}:{topic-id}) or an Amazon EventBridge event source ARN.

Anchor to formatformat

•WebhookSubscriptionFormat

Response format to filter by.

Anchor to topicstopics

•[WebhookSubscriptionTopic!]

List of webhook subscription topics to filter by.

Was this section helpful?

Anchor to MutationsMutations

Anchor to webhookSubscriptionCreate webhookSubscriptionCreate

•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.

Arguments

Anchor to topictopic

•WebhookSubscriptionTopic!

required

The type of event that triggers the webhook.

Anchor to webhookSubscriptionwebhookSubscription

•WebhookSubscriptionInput!

required

Specifies the input fields for a webhook subscription.

Anchor to webhookSubscriptionUpdate 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 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.