feat: change default webhook path to /webhooks/github/

- Update default github_app_route from "/" to "/webhooks/github/"
- Update fallback webhook route defaults in core.py
- Update documentation and code comments to reflect new default
- Update sample configurations and README files for consistency
- Update curl example in main README to use new default path

BREAKING CHANGE: Default webhook path changed from "/" to "/webhooks/github/".
Existing GitHub App webhook URLs need to be updated in GitHub App settings.

Author: primetheus

CHANGELOG.md

@@ -19,13 +19,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Restructured samples into numbered progression
 - Updated README with detailed OAuth2 and rate limiting documentation
 - Consistent issue auto-closing across all samples
+- Default webhook path changed from `/` to `/webhooks/github/`
 
 ### Removed
 - Deprecated cruel_closer and oauth2_example samples
 
 ### Breaking Changes
 - OAuth2 routes now require oauth_session_secret parameter
 - Rate limiting parameters added to GitHubApp constructor
+- Default webhook path changed from `/` to `/webhooks/github/` - update your GitHub App webhook URL configuration
 
 ## [0.2.0] - 2025-09-11
 

README.md

@@ -40,7 +40,7 @@ The above function will do `stuff here` for _every_ `issues` event received. Thi
 
 Inside the function, you can access the received request via the conveniently named `request` variable. You can access its payload by simply getting it: `request.payload`
 
-You can find a complete example (containing this cruel_closer function), in the samples folder of this repo. It is a fully functioning FastAPI Github App.
+You can find examples in the samples folder of this repo. The [samples](./samples/) include fully functioning FastAPI GitHub Apps demonstrating different features.
 
 #### Run it locally
 
@@ -60,15 +60,13 @@ uvicorn app:app --host 0.0.0.0 --port 5005 --reload --workers 1
 Now, you can send requests! The port is 5005 by default but that can also be overridden. Check `uvicorn app:app --help` for more details. Anyway! Now, on to sending test payloads!
 
 ```bash
-curl -H "X-GitHub-Event: <your_event>" -H "Content-Type: application/json" -X POST -d @./path/to/payload.json http://localhost:5005
+curl -H "X-GitHub-Event: <your_event>" -H "Content-Type: application/json" -X POST -d @./path/to/payload.json http://localhost:5005/webhooks/github/
 ```
 
 #### Install your GitHub App
 
 **Settings** > **Applications** > **Configure**
 
-> If you were to install the cruel closer app, any repositories that you give the GitHub app access to will cruelly close all new issues, be careful.
-
 #### Deploy your GitHub App
 
 Bear in mind that you will need to run the app _somewhere_. It is possible, and fairly easy, to host the app in something like Kubernetes, or simply containerised, in a machine somewhere. You will need to be careful to expose the FastAPI app port to the outside world so the app can receive the payloads from Github. The deployed FastAPI app will need to be reachable from the same URL you set as the `webhook url`. However, this is getting a little bit into Docker/Kubernetes territory so we will not go too deep.
@@ -77,14 +75,13 @@ Bear in mind that you will need to run the app _somewhere_. It is possible, and
 
 ### `GitHubApp` Instance Attributes
 
-`payload`: In the context of a hook request, a Python dict representing the hook payload (raises a `RuntimeError`
-outside a hook context).
+`payload`: In the context of a webhook request, a Python dict representing the hook payload (raises a `GitHubAppError` outside a webhook context).
 
 `installation_token`: The token used to authenticate as the app installation. This can be used to call api's not supported by `GhApi` like [Github's GraphQL API](https://docs.github.com/en/graphql/reference)
 
 ### `GithubApp` Instance Methods
 
-`client`: a [GhApi](https://ghapi.fast.ai/) client authenticated as the app installation (raises a `RuntimeError` inside a hook context without a valid request)
+`client`: a [GhApi](https://ghapi.fast.ai/) client authenticated as the app installation (raises a `GitHubAppError` outside a webhook context without a valid installation)
 
 ## Rate Limiting
 
@@ -158,7 +155,7 @@ FastAPI-GitHubApp includes built-in OAuth2 support for user authentication and a
 
 ### Setup
 
-OAuth2 is enabled when you provide both `oauth_client_id` and `oauth_client_secret`. The `oauth_session_secret` is **required** for session management:
+OAuth2 is enabled when you provide both `oauth_client_id` and `oauth_client_secret` (via constructor parameters or environment variables). The `oauth_session_secret` is **required** for session management:
 
 ```python
 from githubapp import GitHubApp
@@ -168,7 +165,7 @@ github_app = GitHubApp(
     github_app_id=12345,
     github_app_key=private_key,
     github_app_secret=webhook_secret,
-    # OAuth2 configuration - all required for OAuth2 to work
+    # OAuth2 configuration - required for OAuth2 to work
     oauth_client_id="your_oauth_client_id",
     oauth_client_secret="your_oauth_client_secret", 
     oauth_session_secret="your-secret-key-for-jwt",  # Required!
@@ -180,6 +177,8 @@ github_app = GitHubApp(
 )
 ```
 
+Alternatively, use environment variables (see Environment Variables section below):
+
 ### OAuth2 Routes
 
 When OAuth2 is configured, these routes are automatically mounted:
@@ -331,19 +330,15 @@ Environment variables use the `GITHUBAPP_OAUTH_` prefix (see Configuration table
 | `GITHUBAPP_ENABLE_OAUTH` | | `True` | Enable/disable OAuth2 routes when fully configured |
 | `GITHUBAPP_OAUTH_ROUTES_PREFIX` | | `/auth/github` | OAuth2 routes prefix |
 
-You can find an example on how to init all these config variables in the [cruel_closer sample app](./samples/cruel_closer)
+You can find an example on how to init all these config variables in the [basic webhook sample app](./samples/01-basic-webhook)
 
 #### OAuth2 Example
 
-The [oauth2_example](./samples/oauth2_example) demonstrates GitHub OAuth2 authentication with web interface, protected routes, and session management. It shows two approaches:
+The [OAuth2 integration sample](./samples/03-oauth2-integration) demonstrates GitHub OAuth2 authentication with web interface, protected routes, and session management. It shows two approaches:
 
 - **Environment-only configuration** (recommended): Load all settings from environment variables
 - **Constructor parameters**: Pass OAuth2 settings explicitly to GitHubApp
 
-#### Cruel Closer
-
-The cruel-closer sample app will use information of the received payload (which is received every time an issue is opened), will find said issue and **close it** without regard.
-
 ### Inspiration
 This was inspired by the following projects:
 - https://github.com/ffalor/flask-githubapplication

samples/02-configuration/constructor.py

@@ -24,7 +24,7 @@ def _env_bytes(name: str):
     github_app_id=int(os.getenv("GITHUBAPP_ID", "0")) or None,
     github_app_key=_env_bytes("GITHUBAPP_PRIVATE_KEY"),
     github_app_secret=_env_bytes("GITHUBAPP_WEBHOOK_SECRET"),
-    github_app_route=os.getenv("GITHUBAPP_WEBHOOK_PATH", "/webhooks/github"),
+    github_app_route=os.getenv("GITHUBAPP_WEBHOOK_PATH", "/webhooks/github/"),
 )
 
 

samples/03-oauth2-integration/.env.example

@@ -2,7 +2,7 @@
 GITHUBAPP_ID=12345
 GITHUBAPP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nYour-GitHub-App-Private-Key-Here\n-----END RSA PRIVATE KEY-----"
 GITHUBAPP_WEBHOOK_SECRET=your-webhook-secret-here
-GITHUBAPP_WEBHOOK_PATH=/webhooks/github
+GITHUBAPP_WEBHOOK_PATH=/webhooks/github/
 
 # OAuth2 Configuration (required for OAuth2 functionality)
 GITHUBAPP_OAUTH_CLIENT_ID=Iv1.your-oauth-client-id

samples/03-oauth2-integration/README.md

@@ -16,7 +16,7 @@ This example demonstrates OAuth2 authentication with GitHub Apps and issue manag
 
 Create a GitHub App with these settings:
 - **Homepage URL**: `http://localhost:8000`
-- **Webhook URL**: `http://localhost:8000/webhooks/github`
+- **Webhook URL**: `http://localhost:8000/webhooks/github/`
 - **Authorization callback URL**: `http://localhost:8000/auth/github/callback`
 
 Required permissions:

samples/04-advanced-features/.env.example

@@ -2,4 +2,4 @@
 GITHUBAPP_ID=12345
 GITHUBAPP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nYour-GitHub-App-Private-Key-Here\n-----END RSA PRIVATE KEY-----"
 GITHUBAPP_WEBHOOK_SECRET=your-webhook-secret-here
-GITHUBAPP_WEBHOOK_PATH=/webhooks/github
+GITHUBAPP_WEBHOOK_PATH=/webhooks/github/

samples/04-advanced-features/README.md

@@ -16,7 +16,7 @@ This example demonstrates advanced GitHub App features including rate limiting,
 
 Create a GitHub App with these settings:
 - **Homepage URL**: `http://localhost:8000`
-- **Webhook URL**: `http://localhost:8000/webhooks/github`
+- **Webhook URL**: `http://localhost:8000/webhooks/github/`
 
 Required permissions:
 - **Issues**: Write (to close issues and add comments)

src/githubapp/core.py

@@ -177,7 +177,7 @@ def __init__(
         github_app_key: bytes = None,
         github_app_secret: bytes = None,
         github_app_url: str = None,
-        github_app_route: str = "/",
+        github_app_route: str = "/webhooks/github/",
         # OAuth2 (optional)
         oauth_client_id: str = None,
         oauth_client_secret: str = None,
@@ -198,7 +198,7 @@ def __init__(
         self.secret = github_app_secret
         self.router = APIRouter()
         self._initialized = False
-        self._webhook_route = github_app_route or "/"
+        self._webhook_route = github_app_route or "/webhooks/github/"
         # OAuth2 setup (moved to init_app to support env vars)
         self.oauth = None
         self._enable_oauth = False
@@ -338,7 +338,7 @@ def init_app(self, app: FastAPI, *, route: str = "/"):
         `GITHUBAPP_WEBHOOK_PATH`:
 
             Path used for GitHub hook requests as a string.
-            Default: '/'
+            Default: '/webhooks/github/'
         """
         # Idempotent setup: avoid mounting more than once
         if self._initialized:
@@ -348,7 +348,7 @@ def init_app(self, app: FastAPI, *, route: str = "/"):
             return
 
         # Register router endpoint for GitHub webhook
-        self._webhook_route = route or self._webhook_route or "/"
+        self._webhook_route = route or self._webhook_route or "/webhooks/github/"
         self.router.post(self._webhook_route)(self._handle_request)
         app.include_router(self.router)
         # copy config from FastAPI app