What Is the Webhook Endpoint for GitHub Integration in Kaneo?

The webhook endpoint for GitHub integration in Kaneo is POST /github/webhook, which receives GitHub App events and processes them through the handleGithubWebhook function located in apps/api/src/plugins/github/webhook-handler.ts.

Kaneo exposes a dedicated REST route to ingest real-time events from GitHub Apps, enabling automated workflows for issue tracking and project management. This endpoint validates incoming payloads using the Octokit library and dispatches them to internal event listeners. Understanding the exact path and handler implementation is essential for configuring your GitHub App webhook settings correctly.

Webhook Endpoint Path and Method

The GitHub integration endpoint listens for incoming webhook deliveries at the following path:

• Endpoint: POST /github/webhook
• Full URL: https://<your-kaneo-host>/github/webhook

According to the Kaneo source code, this route is registered in the OpenAPI router configuration and handles all GitHub App event types, including issues, pull_request, and push events.

Core Handler Implementation

The webhook logic resides in the API plugin layer, where the handler validates signatures and routes events to the appropriate internal processors.

Primary Handler Function

In apps/api/src/plugins/github/webhook-handler.ts, the handleGithubWebhook function processes incoming requests:

// apps/api/src/plugins/github/webhook-handler.ts
import { getGithubApp } from "./utils/github-app";

export async function handleGithubWebhook(c) {
  const githubApp = getGithubApp();
  if (!githubApp) {
    throw new HTTPException(500, { message: "GitHub App not configured" });
  }

  // Verify signature, parse payload and route to listeners (e.g. issues.opened)
  await githubApp.webhooks.verifyAndReceive(c.req.raw);
}

This function retrieves the singleton GitHub App instance via getGithubApp() and invokes verifyAndReceive() to cryptographically validate the X-Hub-Signature header before processing the payload.

GitHub App Singleton

The handler depends on getGithubApp(), defined in apps/api/src/plugins/github/utils/github-app.ts, which initializes and returns a configured Octokit App instance used across the webhook lifecycle.

Route Registration

The endpoint is bound to the HTTP path in the API router configuration. In apps/api/src/openapi.ts, the route is explicitly registered with the OpenAPI schema:

// apps/api/src/openapi.ts (excerpt)
router.post(
  "/github/webhook",
  { schema: {/* … OpenAPI schema … */} },
  handleGithubWebhook,
);

This registration maps the /github/webhook path to the handler function, ensuring that all POST requests to this endpoint are processed by the GitHub plugin.

Configuring Your GitHub App

To enable the integration, configure your GitHub App's webhook URL to point to this endpoint:

# GitHub App settings

Webhook URL: https://kaneo.example.com/github/webhook

The endpoint expects the standard GitHub webhook headers, including X-GitHub-Event and X-Hub-Signature, which the verifyAndReceive method validates against your configured webhook secret.

Testing the Endpoint Locally

You can test the webhook handler locally by simulating a GitHub event delivery:

# Using curl (replace <payload> with a real GitHub event JSON)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: issues" \
  -H "X-GitHub-Delivery: <uuid>" \
  -H "X-Hub-Signature: <computed-sha1>" \
  --data @payload.json \
  http://localhost:3000/github/webhook

Ensure your local Kaneo instance has the GITHUB_APP_ID and GITHUB_PRIVATE_KEY environment variables configured so that getGithubApp() initializes correctly.

Client-Side Integration

While the webhook endpoint receives events from GitHub, client-side interactions with GitHub integration are managed through fetchers in the web application. The apps/web/src/fetchers/github-integration/ directory contains utilities for creating and managing GitHub integrations via the frontend, though these interact with standard REST endpoints rather than the webhook receiver itself.

Summary

• The webhook endpoint for GitHub integration is POST /github/webhook.
• The handler function handleGithubWebhook is implemented in apps/api/src/plugins/github/webhook-handler.ts.
• Signature verification is performed using githubApp.webhooks.verifyAndReceive() from the Octokit library.
• Route registration occurs in apps/api/src/openapi.ts using the OpenAPI router.
• Configure your GitHub App's Webhook URL to point to https://<your-host>/github/webhook.

Frequently Asked Questions

What HTTP method does the Kaneo GitHub webhook endpoint use?

The Kaneo GitHub webhook endpoint accepts POST requests exclusively. GitHub sends all webhook events as HTTP POST payloads to this endpoint, which then validates and processes them according to the event type specified in the X-GitHub-Event header.

Where is the webhook signature validation logic located?

The signature validation logic is located in apps/api/src/plugins/github/webhook-handler.ts within the handleGithubWebhook function. Specifically, the githubApp.webhooks.verifyAndReceive() method from the Octokit library handles cryptographic verification of the X-Hub-Signature header against the configured webhook secret.

How do I troubleshoot a "GitHub App not configured" error?

This error originates in apps/api/src/plugins/github/webhook-handler.ts when getGithubApp() returns null, indicating missing environment variables. Ensure that GITHUB_APP_ID and GITHUB_PRIVATE_KEY are properly configured in your environment so that the singleton initializer in apps/api/src/plugins/github/utils/github-app.ts can instantiate the Octokit App client.

Can I change the base path of the GitHub webhook endpoint?

The path /github/webhook is hardcoded in the route registration within apps/api/src/openapi.ts. To modify this path, you must update the route definition in that file and ensure your GitHub App settings reflect the new URL. The handler logic itself in webhook-handler.ts remains agnostic to the specific path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}