Handle GitHub webhook non-POST methods and cleanup installs

Improves the GitHub webhook route to handle non-POST requests (e.g., health checks) by logging and returning 200 without signature validation. Adds a method to delete GitHub App installations in the service, and updates project resolver to remove GitHub installations on disconnect. Also standardizes error key to 'apiError' in OAuth redirects and improves webhook logging.

Author: neSpecc

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hawk.api",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "main": "index.ts",
   "license": "BUSL-1.1",
   "scripts": {

src/integrations/github/routes.ts

@@ -208,6 +208,8 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
     logger(prefix, ...logArgs);
   }
 
+  const WEBHOOK_LOG_PREFIX = '[🍏 🍎 ✨ Webhook] ';
+
   /**
    * GET /integration/github/connect?projectId=<projectId>
    * Initiate GitHub integration connection
@@ -290,13 +292,13 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
        */
       if (!code || typeof code !== 'string') {
         return res.redirect(buildGarageRedirectUrl('/', {
-          error: 'Missing or invalid OAuth code',
+          apiError: 'Missing or invalid OAuth code',
         }));
       }
 
       if (!state || typeof state !== 'string') {
         return res.redirect(buildGarageRedirectUrl('/', {
-          error: 'Missing or invalid state',
+          apiError: 'Missing or invalid state',
         }));
       }
 
@@ -310,7 +312,7 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
         log('warn', `Invalid or expired state: ${sgr(state.slice(0, 8), Effect.ForegroundGray)}...`);
 
         return res.redirect(buildGarageRedirectUrl('/', {
-          error: 'Invalid or expired state. Please try connecting again.',
+          apiError: 'Invalid or expired state. Please try connecting again.',
         }));
       }
 
@@ -508,16 +510,47 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
   /**
    * POST /integration/github/webhook
    * Handle GitHub App webhook events
+   *
+   * GitHub delivers signed webhook payloads as POST requests.
+   * For non-POST methods (e.g. GET/HEAD checks), respond with 200 without signature validation.
    */
-  router.post('/webhook', express.raw({ type: 'application/json' }), async (req, res, next) => {
+  router.all('/webhook', express.raw({ type: 'application/json' }), async (req, res, next) => {
+    log('info', `${WEBHOOK_LOG_PREFIX}/webhook route called with method ${req.method}`);
+
+    /**
+     * For non-POST methods (for example, GitHub hitting Setup URL or doing health checks),
+     * just log query parameters and respond with 200 without signature validation.
+     */
+    if (req.method !== 'POST') {
+      const { code, installation_id, setup_action, state, ...restQuery } = req.query as Record<string, unknown>;
+
+      if (code || installation_id || state || setup_action) {
+        // eslint-disable-next-line @typescript-eslint/camelcase, camelcase
+        log('info', `${WEBHOOK_LOG_PREFIX}Received non-POST request on /webhook with OAuth-like params`, {
+          // eslint-disable-next-line @typescript-eslint/camelcase, camelcase
+          code,
+          installation_id,
+          setup_action,
+          state,
+          query: restQuery,
+        });
+      } else {
+        log('info', `${WEBHOOK_LOG_PREFIX}Received non-POST request on /webhook without signature (likely a health check or misconfigured URL)`, {
+          query: req.query,
+        });
+      }
+
+      return res.status(200).json({ ok: true });
+    }
+
     try {
       /**
        * Get webhook secret from environment
        */
       const webhookSecret = process.env.GITHUB_WEBHOOK_SECRET;
 
       if (!webhookSecret) {
-        log('error', 'GITHUB_WEBHOOK_SECRET is not configured');
+        log('error', `${WEBHOOK_LOG_PREFIX}GITHUB_WEBHOOK_SECRET is not configured`);
         res.status(500).json({ error: 'Webhook secret not configured' });
 
         return;
@@ -530,7 +563,7 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
       const signature = req.headers['x-hub-signature-256'] as string | undefined;
 
       if (!signature) {
-        log('warn', 'Missing X-Hub-Signature-256 header');
+        log('warn', `${WEBHOOK_LOG_PREFIX}Missing X-Hub-Signature-256 header`);
 
         return res.status(401).json({ error: 'Missing signature header' });
       }
@@ -569,7 +602,7 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
       }
 
       if (!signatureValid) {
-        log('warn', 'Invalid webhook signature');
+        log('warn', `${WEBHOOK_LOG_PREFIX}Invalid webhook signature`);
 
         return res.status(401).json({ error: 'Invalid signature' });
       }
@@ -584,15 +617,15 @@ export function createGitHubRouter(factories: ContextFactories): express.Router
       try {
         payloadData = JSON.parse(payload.toString()) as GitHubWebhookPayload;
       } catch (error) {
-        log('error', 'Failed to parse webhook payload:', error);
+        log('error', `${WEBHOOK_LOG_PREFIX}Failed to parse webhook payload:`, error);
 
         return res.status(400).json({ error: 'Invalid JSON payload' });
       }
 
       const eventType = req.headers['x-github-event'] as string | undefined;
       const installationId = payloadData.installation?.id?.toString();
 
-      log('info', `Received webhook event: ${sgr(eventType || 'unknown', Effect.ForegroundCyan)}`);
+      log('info', `${WEBHOOK_LOG_PREFIX}Received webhook event: ${sgr(eventType || 'unknown', Effect.ForegroundCyan)}`);
 
       /**
        * Handle installation.deleted event

src/integrations/github/service.ts

@@ -188,6 +188,22 @@ export class GitHubService {
     return `https://github.com/apps/${this.appSlug}/installations/new?state=${encodeURIComponent(state)}&redirect_url=${encodeURIComponent(redirectUrl)}`;
   }
 
+  /**
+   * Delete GitHub App installation by installation ID
+   *
+   * @param {string} installationId - GitHub App installation ID
+   * @returns {Promise<void>}
+   */
+  public async deleteInstallation(installationId: string): Promise<void> {
+    const token = this.createJWT();
+    const octokit = this.createOctokit(token);
+
+    await octokit.rest.apps.deleteInstallation({
+      // eslint-disable-next-line @typescript-eslint/camelcase, camelcase
+      installation_id: parseInt(installationId, 10),
+    });
+  }
+
   /**
    * Get installation information
    *

src/resolvers/project.js

@@ -9,6 +9,7 @@ const getEventsFactory = require('./helpers/eventsFactory').default;
 const ProjectToWorkspace = require('../models/projectToWorkspace');
 const { dateFromObjectId } = require('../utils/dates');
 const ProjectModel = require('../models/project').default;
+const { GitHubService } = require('../integrations/github/service');
 
 const EVENTS_GROUP_HASH_INDEX_NAME = 'groupHashUnique';
 const REPETITIONS_GROUP_HASH_INDEX_NAME = 'groupHash_hashed';
@@ -414,9 +415,20 @@ module.exports = {
       }
 
       try {
+        /**
+         * If Task Manager is configured with GitHub and has installationId,
+         * try to delete GitHub App installation as part of disconnect
+         */
+        const taskManager = project.taskManager;
+
+        if (taskManager && taskManager.type === 'github' && taskManager.config?.installationId) {
+          const githubService = new GitHubService();
+
+          await githubService.deleteInstallation(taskManager.config.installationId);
+        }
+
         /**
          * Remove taskManager field from project
-         * Set updatedAt to current date
          */
         return await project.updateProject({
           taskManager: null,