diff --git a/docs/updates.md b/docs/updates.md
new file mode 100644
index 0000000..2d9674f
--- /dev/null
+++ b/docs/updates.md
@@ -0,0 +1,16 @@
+The Desktop app is capable of self-updating on macOS and Windows.
+The update server base url is configurable as `update_base_url` in config.json and can be served by a static file host,
+CDN or object storage.
+
+Currently all packaging & deployment is handled by https://github.com/vector-im/element-builder/
+
+# Windows
+
+On Windows the update mechanism used is [Squirrel.Windows](https://github.com/Squirrel/Squirrel.Windows)
+and can be served by any compatible Squirrel server, such as https://github.com/Tiliq/squirrel-server
+
+# macOS
+
+On macOS the update mechanism used is [Squirrel.Mac](https://github.com/Squirrel/Squirrel.Mac)
+using the newer JSON format as documented [here](https://github.com/Squirrel/Squirrel.Mac#update-file-json-format).
+
diff --git a/src/updater.ts b/src/updater.ts
index 77fa401..ba973e7 100644
--- a/src/updater.ts
+++ b/src/updater.ts
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { app, autoUpdater, ipcMain } from "electron";
+import { autoUpdater, ipcMain } from "electron";
 
 const UPDATE_POLL_INTERVAL_MS = 60 * 60 * 1000;
 const INITIAL_UPDATE_DELAY_MS = 30 * 1000;
@@ -50,20 +50,14 @@ export function start(updateBaseUrl: string): void {
     }
     try {
         let url: string;
-        // For reasons best known to Squirrel, the way it checks for updates
-        // is completely different between macOS and windows. On macOS, it
-        // hits a URL that either gives it a 200 with some json or
-        // 204 No Content. On windows it takes a base path and looks for
-        // files under that path.
+        let serverType: "json" | undefined;
+
         if (process.platform === 'darwin') {
-            // include the current version in the URL we hit. Electron doesn't add
-            // it anywhere (apart from the User-Agent) so it's up to us. We could
-            // (and previously did) just use the User-Agent, but this doesn't
-            // rely on NSURLConnection setting the User-Agent to what we expect,
-            // and also acts as a convenient cache-buster to ensure that when the
-            // app updates it always gets a fresh value to avoid update-looping.
-            url = `${updateBaseUrl}macos/?localVersion=${encodeURIComponent(app.getVersion())}`;
+            // On macOS it takes a JSON file with a map between versions and their URLs
+            url = `${updateBaseUrl}macos/releases.json`;
+            serverType = "json";
         } else if (process.platform === 'win32') {
+            // On windows it takes a base path and looks for files under that path.
             url = `${updateBaseUrl}win32/${process.arch}/`;
         } else {
             // Squirrel / electron only supports auto-update on these two platforms.
@@ -75,7 +69,7 @@ export function start(updateBaseUrl: string): void {
 
         if (url) {
             console.log(`Update URL: ${url}`);
-            autoUpdater.setFeedURL({ url });
+            autoUpdater.setFeedURL({ url, serverType });
             // We check for updates ourselves rather than using 'updater' because we need to
             // do it in the main process (and we don't really need to check every 10 minutes:
             // every hour should be just fine for a desktop app)