update_webhook

Instructions

Implementation Reference

• src/tools/webhooks.ts:315-353 (handler)

  The handler function for the 'update_webhook' tool. It builds a webhookSubscription payload from optional args (callbackUrl, format, includeFields, metafieldNamespaces), calls the Shopify webhookSubscriptionUpdate mutation, throws on user errors, and returns a summary of the updated webhook.

    async (args) => {
      const webhookSubscription: Record<string, unknown> = {};
      if (args.callbackUrl !== undefined) {
        webhookSubscription.callbackUrl = args.callbackUrl;
      }
      if (args.format !== undefined) webhookSubscription.format = args.format;
      if (args.includeFields !== undefined) {
        webhookSubscription.includeFields = args.includeFields;
      }
      if (args.metafieldNamespaces !== undefined) {
        webhookSubscription.metafieldNamespaces = args.metafieldNamespaces;
      }
  
      const data = await client.graphql<{
        webhookSubscriptionUpdate: {
          webhookSubscription: WebhookSubscriptionNode | null;
          userErrors: ShopifyUserError[];
        };
      }>(WEBHOOK_UPDATE_MUTATION, {
        id: args.id,
        webhookSubscription,
      });
      throwIfUserErrors(
        data.webhookSubscriptionUpdate.userErrors,
        "webhookSubscriptionUpdate",
      );
      const w = data.webhookSubscriptionUpdate.webhookSubscription;
      return {
        content: [
          {
            type: "text" as const,
            text: w
              ? `Updated webhook ${w.topic} → ${w.endpoint.callbackUrl ?? "(endpoint)"} — ${w.id}`
              : `Updated webhook ${args.id}.`,
          },
        ],
      };
    },
  );

• src/tools/webhooks.ts:164-170 (schema)

  Zod schema for the update_webhook tool input. Defines 'id' (required GID), and optional fields: callbackUrl, format (JSON/XML), includeFields, and metafieldNamespaces.

  const updateWebhookSchema = {
    id: z.string().describe("Webhook subscription GID to update."),
    callbackUrl: z.string().url().optional(),
    format: z.enum(["JSON", "XML"]).optional(),
    includeFields: z.array(z.string()).optional(),
    metafieldNamespaces: z.array(z.string()).optional(),
  };

• src/tools/webhooks.ts:311-353 (registration)

  Registration of 'update_webhook' via server.tool() inside the registerWebhookTools function. The tool is registered with name 'update_webhook', a descriptive string, the updateWebhookSchema, and the async handler.

  server.tool(
    "update_webhook",
    "Modify an existing webhook subscription's callback URL, payload format, includeFields filter, or metafield-namespace filter. Topic cannot be changed — to switch event types, delete and recreate the subscription. Use when migrating an endpoint to a new domain, switching from JSON to XML, or tightening payload size by adding includeFields. Omitted parameters are left unchanged.",
    updateWebhookSchema,
    async (args) => {
      const webhookSubscription: Record<string, unknown> = {};
      if (args.callbackUrl !== undefined) {
        webhookSubscription.callbackUrl = args.callbackUrl;
      }
      if (args.format !== undefined) webhookSubscription.format = args.format;
      if (args.includeFields !== undefined) {
        webhookSubscription.includeFields = args.includeFields;
      }
      if (args.metafieldNamespaces !== undefined) {
        webhookSubscription.metafieldNamespaces = args.metafieldNamespaces;
      }
  
      const data = await client.graphql<{
        webhookSubscriptionUpdate: {
          webhookSubscription: WebhookSubscriptionNode | null;
          userErrors: ShopifyUserError[];
        };
      }>(WEBHOOK_UPDATE_MUTATION, {
        id: args.id,
        webhookSubscription,
      });
      throwIfUserErrors(
        data.webhookSubscriptionUpdate.userErrors,
        "webhookSubscriptionUpdate",
      );
      const w = data.webhookSubscriptionUpdate.webhookSubscription;
      return {
        content: [
          {
            type: "text" as const,
            text: w
              ? `Updated webhook ${w.topic} → ${w.endpoint.callbackUrl ?? "(endpoint)"} — ${w.id}`
              : `Updated webhook ${args.id}.`,
          },
        ],
      };
    },
  );

• src/tools/webhooks.ts:98-113 (schema)

  The GraphQL mutation (WEBHOOK_UPDATE_MUTATION) used by the handler to call Shopify's webhookSubscriptionUpdate API.

  const WEBHOOK_UPDATE_MUTATION = /* GraphQL */ `
    mutation WebhookUpdate($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) {
      webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) {
        webhookSubscription {
          id
          topic
          format
          endpoint {
            __typename
            ... on WebhookHttpEndpoint { callbackUrl }
          }
        }
        userErrors { field message }
      }
    }
  `;