--- title: webhookSubscriptionUpdate - GraphQL Admin description: >- 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). api_version: 2024-10 api_name: admin type: mutation api_type: graphql source_url: html: >- https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/webhookSubscriptionUpdate md: >- https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/webhookSubscriptionUpdate.txt --- # webhook​Subscription​Update 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). ## Arguments * id [ID!](https://shopify.dev/docs/api/admin-graphql/2024-10/scalars/ID) required The ID of the webhook subscription to update. * webhook​Subscription [Webhook​Subscription​Input!](https://shopify.dev/docs/api/admin-graphql/2024-10/input-objects/WebhookSubscriptionInput) required Specifies the input fields for a webhook subscription. *** ## Webhook​Subscription​Update​Payload returns * user​Errors [\[User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/UserError) non-null The list of errors that occurred from executing the mutation. * webhook​Subscription [Webhook​Subscription](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/WebhookSubscription) The webhook subscription that was updated. *** ## Examples * ### Modify an existing Webhook #### Query ```graphql mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } } ``` #### Variables ```json { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } }", "variables": { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } }`, { variables: { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } } QUERY variables = { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } }`, "variables": { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } }, }, }); ``` #### Response ```json { "webhookSubscriptionUpdate": { "userErrors": [], "webhookSubscription": { "id": "gid://shopify/WebhookSubscription/525699895", "topic": "ORDERS_CREATE", "endpoint": { "__typename": "WebhookHttpEndpoint", "callbackUrl": "https://example.org/aValidEndpoint" }, "apiVersion": { "handle": "unstable" } } } } ``` * ### Update the callback URL of a webhook subscription #### Query ```graphql mutation webhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } } ``` #### Variables ```json { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation webhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } }", "variables": { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation webhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } }`, { variables: { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation webhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } } QUERY variables = { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation webhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } }`, "variables": { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } }, }, }); ``` #### Response ```json { "webhookSubscriptionUpdate": { "userErrors": [], "webhookSubscription": { "id": "gid://shopify/WebhookSubscription/525699895", "topic": "ORDERS_CREATE", "endpoint": { "callbackUrl": "https://example.org/aValidEndpoint" } } } } ``` * ### webhookSubscriptionUpdate reference [Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20WebhookSubscriptionUpdate\(%24id%3A%20ID!%2C%20%24webhookSubscription%3A%20WebhookSubscriptionInput!\)%20%7B%0A%20%20webhookSubscriptionUpdate\(id%3A%20%24id%2C%20webhookSubscription%3A%20%24webhookSubscription\)%20%7B%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%20%20webhookSubscription%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%20%20topic%0A%20%20%20%20%20%20endpoint%20%7B%0A%20%20%20%20%20%20%20%20__typename%0A%20%20%20%20%20%20%20%20...%20on%20WebhookHttpEndpoint%20%7B%0A%20%20%20%20%20%20%20%20%20%20callbackUrl%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20...%20on%20WebhookEventBridgeEndpoint%20%7B%0A%20%20%20%20%20%20%20%20%20%20arn%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20...%20on%20WebhookPubSubEndpoint%20%7B%0A%20%20%20%20%20%20%20%20%20%20pubSubProject%0A%20%20%20%20%20%20%20%20%20%20pubSubTopic%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20apiVersion%20%7B%0A%20%20%20%20%20%20%20%20handle%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22id%22%3A%20%22gid%3A%2F%2Fshopify%2FWebhookSubscription%2F525699895%22%2C%0A%20%20%22webhookSubscription%22%3A%20%7B%0A%20%20%20%20%22callbackUrl%22%3A%20%22https%3A%2F%2Fexample.org%2FaValidEndpoint%22%0A%20%20%7D%0A%7D) ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation WebhookSubscriptionUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) { webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) { userErrors { field message } webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } ... on WebhookEventBridgeEndpoint { arn } ... on WebhookPubSubEndpoint { pubSubProject pubSubTopic } } apiVersion { handle } } } }`, { variables: { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } }, }, ); const data = await response.json(); ``` ## Input variables JSON ```json { "id": "gid://shopify/WebhookSubscription/525699895", "webhookSubscription": { "callbackUrl": "https://example.org/aValidEndpoint" } } ``` ## Response JSON ```json { "webhookSubscriptionUpdate": { "userErrors": [], "webhookSubscription": { "id": "gid://shopify/WebhookSubscription/525699895", "topic": "ORDERS_CREATE", "endpoint": { "__typename": "WebhookHttpEndpoint", "callbackUrl": "https://example.org/aValidEndpoint" }, "apiVersion": { "handle": "unstable" } } } } ```