delete_webhook

Instructions

Implementation Reference

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

  The handler function for the 'delete_webhook' tool. It accepts an 'id' (webhook subscription GID), executes the WEBHOOK_DELETE_MUTATION GraphQL mutation, throws on 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)

  The Zod schema for the 'delete_webhook' tool input. It defines a single required field: 'id' (string) described as 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 on the MCP server via server.tool(), called inside registerWebhookTools() which is invoked from src/server.ts line 66.

  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/server.ts:66-66 (registration)

  Where registerWebhookTools is called to register all webhook tools (including delete_webhook) on the MCP server instance.

  registerWebhookTools(s, shopify);

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

  The WEBHOOK_DELETE_MUTATION GraphQL mutation used by the delete_webhook handler. It calls webhookSubscriptionDelete(id) and returns the deleted ID plus any user errors.

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