delete_webhook

Instructions

Implementation Reference

• src/tools/webhooks.ts:355-381 (handler)

  The handler function for the 'delete_webhook' tool. It takes an 'id' argument (a webhook subscription GID), executes the WEBHOOK_DELETE_MUTATION GraphQL mutation, checks for user errors, and returns a success message with the deleted GID or a no-op message.

  server.tool(
    "delete_webhook",
    "Permanently unsubscribe from an event topic by deleting the webhook subscription. Stops all future deliveries to that endpoint for that topic — irreversible (you'd have to re-create with create_webhook). Use when retiring an integration or switching topics. Returns the deleted GID, or a no-op message if nothing matched.",
    deleteWebhookSchema,
    async (args) => {
      const data = await client.graphql<{
        webhookSubscriptionDelete: {
          deletedWebhookSubscriptionId: string | null;
          userErrors: ShopifyUserError[];
        };
      }>(WEBHOOK_DELETE_MUTATION, { id: args.id });
      throwIfUserErrors(
        data.webhookSubscriptionDelete.userErrors,
        "webhookSubscriptionDelete",
      );
      return {
        content: [
          {
            type: "text" as const,
            text: data.webhookSubscriptionDelete.deletedWebhookSubscriptionId
              ? `Deleted webhook ${data.webhookSubscriptionDelete.deletedWebhookSubscriptionId}.`
              : "No webhook matched; nothing deleted.",
          },
        ],
      };
    },
  );

• src/tools/webhooks.ts:172-174 (schema)

  Input schema for the 'delete_webhook' tool: a single required field 'id' (string, the webhook subscription GID to delete).

  const deleteWebhookSchema = {
    id: z.string().describe("Webhook subscription GID to delete."),
  };

• src/tools/webhooks.ts:355-381 (registration)

  Registration of the 'delete_webhook' tool via server.tool(...) with the name 'delete_webhook', a description explaining the action, the deleteWebhookSchema, and the async handler function.

  server.tool(
    "delete_webhook",
    "Permanently unsubscribe from an event topic by deleting the webhook subscription. Stops all future deliveries to that endpoint for that topic — irreversible (you'd have to re-create with create_webhook). Use when retiring an integration or switching topics. Returns the deleted GID, or a no-op message if nothing matched.",
    deleteWebhookSchema,
    async (args) => {
      const data = await client.graphql<{
        webhookSubscriptionDelete: {
          deletedWebhookSubscriptionId: string | null;
          userErrors: ShopifyUserError[];
        };
      }>(WEBHOOK_DELETE_MUTATION, { id: args.id });
      throwIfUserErrors(
        data.webhookSubscriptionDelete.userErrors,
        "webhookSubscriptionDelete",
      );
      return {
        content: [
          {
            type: "text" as const,
            text: data.webhookSubscriptionDelete.deletedWebhookSubscriptionId
              ? `Deleted webhook ${data.webhookSubscriptionDelete.deletedWebhookSubscriptionId}.`
              : "No webhook matched; nothing deleted.",
          },
        ],
      };
    },
  );

• src/tools/webhooks.ts:115-122 (helper)

  The WEBHOOK_DELETE_MUTATION GraphQL mutation string used by the delete_webhook handler. It sends the webhook subscription 'id' to Shopify's webhookSubscriptionDelete mutation and returns the deletedWebhookSubscriptionId plus userErrors.

  const WEBHOOK_DELETE_MUTATION = /* GraphQL */ `
    mutation WebhookDelete($id: ID!) {
      webhookSubscriptionDelete(id: $id) {
        deletedWebhookSubscriptionId
        userErrors { field message }
      }
    }
  `;

• src/shopify/client.ts:65-74 (helper)

  The throwIfUserErrors helper function used in the delete_webhook handler to check and throw if any user errors are returned from the Shopify API.

  export function throwIfUserErrors(
    errors: ShopifyUserError[] | undefined,
    operation: string,
  ): void {
    if (!errors || errors.length === 0) return;
    const messages = errors
      .map((e) => (e.field ? `${e.field.join(".")}: ${e.message}` : e.message))
      .join("; ");
    throw new Error(`Shopify ${operation} userErrors: ${messages}`);
  }