Choose a version:

webhookSubscriptionUpdate

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.

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 Arguments

Arguments

Anchor to idid •ID! required: The ID of the webhook subscription to update.
Anchor to webhookSubscriptionwebhookSubscription •WebhookSubscriptionInput! required: Specifies the input fields for a webhook subscription.

Was this section helpful?

Anchor to WebhookSubscriptionUpdatePayload returnsWebhookSubscriptionUpdatePayload returns

Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to webhookSubscriptionwebhookSubscription •WebhookSubscription: The webhook subscription that was updated.

Was this section helpful?

Examples

Modify an existing Webhook

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"
  }
}

cURL

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"
    }
  }
}'

Remix

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

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

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

{
  "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

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"
  }
}

cURL

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"
    }
  }
}'

Remix

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

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

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

{
  "webhookSubscriptionUpdate": {
    "userErrors": [],
    "webhookSubscription": {
      "id": "gid://shopify/WebhookSubscription/525699895",
      "topic": "ORDERS_CREATE",
      "endpoint": {
        "callbackUrl": "https://example.org/aValidEndpoint"
      }
    }
  }
}

webhookSubscriptionUpdate reference

Examples

Open in GraphiQL

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 {

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();

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 -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"
    }
  }
}'

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();

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"
        }
    },
  },
});

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

{

"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"

}