1. Guides
  2. Release Webhooks

Guides

Release Webhooks

You can configure a webhook URL to receive notifications when a release is published. This is useful for triggering downstream processes like deployment pipelines or notifications.

Setting up a Release Webhook

  1. Go to your app's Settings > General page in the ToDesktop dashboard
  2. In the App Webhooks section, click the + button and select Add Release Webhook
  3. Enter your webhook URL (must begin with https://)
Screenshot showing the App Webhooks section with the Add Release Webhook option

Webhook Secret

When you add a release webhook, ToDesktop generates an HMAC secret key that you can use to verify webhook requests. The secret is displayed in the App Webhooks section of your app settings. Use this secret to validate that incoming webhook requests are genuinely from ToDesktop.

INFO

Keep your webhook secret secure. Never expose it in client-side code or public repositories.

Webhook Payload

When a release is published, ToDesktop sends a POST request to your webhook URL with a JSON body containing information about the release:

        {
  appId: string;                        // Your ToDesktop app ID
  buildId: string;                      // The released build ID
  userId: string;                       // The user who triggered the release
  buildStartedAt: string;               // ISO 8601 timestamp
  buildEndedAt: string;                 // ISO 8601 timestamp
  appName: string;                      // The application name
  appVersion: string;                   // The application version (e.g., "1.2.3")
  appNotarizaionBundleId?: string;      // macOS notarization bundle ID
  electronVersionUsed: string;          // Electron version used in the build
  electronVersionSpecified: string;     // Electron version from package.json
  sourcePackageManager: string;         // Package manager used (npm, yarn, pnpm)
  versionControlInfo?: {                // Git information (if available)
    branchName: string;
    commitDate: string;
    commitId: string;
    commitMessage: string;
    hasUncommittedChanges: boolean;
    repositoryRemoteUrl: string;
    versionControlSystemName: string;
  };
  releaseInfo: {
    latestReleaseBuildId?: string;      // The build ID that is now the latest release
    releaseRedirections?: Array<object>; // Any release redirection rules
  };
}

Verifying Webhook Signatures

Each webhook request includes an X-ToDesktop-HMAC-SHA256 header containing an HMAC signature. To verify the request:

  1. Get your webhook secret from the App Webhooks section in your app settings
  2. Compute the HMAC-SHA256 of the raw request body using your secret
  3. Compare it to the X-ToDesktop-HMAC-SHA256 header value

Example (Node.js):

        const crypto = require('crypto');

function verifyWebhook(requestBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(requestBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature),
  );
}
Previous <- Distributing builds to Mac App Store
Next ToDesktop CLI ->