--- title: webhookSubscriptionUpdate - GraphQL Admin description: >- 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). api_version: 2025-01 api_name: admin type: mutation api_type: graphql source_url: html: >- https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/webhookSubscriptionUpdate md: >- https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/webhookSubscriptionUpdate.md --- # webhook​Subscription​Update 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). ## Arguments * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) required The ID of the webhook subscription to update. * webhook​Subscription [Webhook​Subscription​Input!](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/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/2025-01/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/2025-01/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" } } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` #### 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/2025-01/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" } } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` #### 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) ##### GQL ```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 } } } } ``` ##### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-01/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" } } }' ``` ##### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` ##### 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" } }, }, }); ``` ##### 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) ``` ## 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" } } } } ```