# What Is the Webhook Endpoint for GitHub Integration in Kaneo?

> Discover the Kaneo webhook endpoint for GitHub integration: POST /github/webhook. Learn how it handles GitHub App events efficiently for seamless development workflows.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/github/webhook-handler.ts), the `handleGithubWebhook` function processes incoming requests:

```typescript
// 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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts), the route is explicitly registered with the OpenAPI schema:

```typescript
// 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:

```yaml

# 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:

```bash

# 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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/webhook-handler.ts) remains agnostic to the specific path.