ReCloudStudio/WebHooker
1
0
Fork 0
mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: restructure into core-concept pages and split admin API

Browse source
This commit is contained in:
RhenCloud 2026-08-14 06:41:08 +08:00
parent db49e1f01c
commit a9e50fba50
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
27 changed files with 946 additions and 1203 deletions
Download patch file Download diff file Expand all files Collapse all files

99
docs/api/overview.md
View file

@ -10,52 +10,33 @@ https://your-worker.workers.dev
## Endpoints
| Method | Path | Auth | Description |
|----------|--------------------------------------------|-------------------|--------------------------------------------------------------------|
| `GET` | `/health` | None | Health check |
| `POST` | `/webhook` | HMAC signature | GitHub / Gitea / custom webhook ingestion (provider auto-detected) |
| `POST` | `/webhook/:groupId` | Per-group secret | Per-group webhook ingress (only that group's routes fire) |
| `POST` | `/discord/interactions` | Ed25519 signature | Discord interactions (slash commands, buttons, modals) |
| `POST` | `/telegram/webhook` | Secret token | Telegram updates (bot `/gh` commands) |
| `GET` | `/api/richheader` | None | Open Graph page for the Telegram avatar link-preview card |
| `GET` | `/auth/github` | None | Start GitHub OAuth flow |
| `GET` | `/auth/github/callback` | None | OAuth callback |
| `GET` | `/auth/github/install` | Admin session | Post-install choice page: bind the installation to a group |
| `POST` | `/auth/github/install/bind` | Admin session | Provision the chosen installation binding |
| `DELETE` | `/auth/token/:userId` | Admin session | Revoke user token |
| `POST` | `/api/comment` | Bearer token | Create issue comment |
| `POST` | `/api/merge` | Bearer token | Merge pull request |
| `POST` | `/api/close` | Bearer token | Close pull request |
| `POST` | `/api/react` | Bearer token | Add reaction to issue |
| `GET` | `/admin` | Admin session | Config console UI |
| `GET` | `/admin/login` | None | Start admin sign-in (GitHub OAuth) |
| `GET` | `/admin/logout` | Admin session | Sign out and destroy the session |
| `GET` | `/admin/invite` | Admin session | Accept a group invite (browser page, `?token=…`) |
| `GET` | `/admin/api/me` | Admin session | Current session, scope, groups, and roles |
| `GET` | `/admin/api/routes` | Admin session | List routes (scoped to access) |
| `PUT` | `/admin/api/routes` | Admin session | Replace routes (owner/admin per group) |
| `GET` | `/admin/api/groups` | Admin session | List groups + the signed-in user's role in each |
| `PUT` | `/admin/api/groups` | Admin session | Replace groups (super: all; owner: own only) |
| `GET` | `/admin/api/groups/:id/routes` | Admin session | List a group's routes |
| `PUT` | `/admin/api/groups/:id/routes` | Admin session | Replace a group's routes (owner/admin) |
| `PUT` | `/admin/api/groups/:id/rename` | Admin session | Rename a group (owner); routes/secret/invites follow |
| `GET` | `/admin/api/groups/:id/invites` | Admin session | List pending invites (owner) |
| `POST` | `/admin/api/groups/:id/invites` | Admin session | Create an invite link (owner) |
| `DELETE` | `/admin/api/invites/:token` | Admin session | Revoke an invite (owner) |
| `GET` | `/admin/api/groups/:id/webhook` | Admin session | Group webhook endpoint info (owner) |
| `POST` | `/admin/api/groups/:id/webhook/regenerate` | Admin session | Generate/regenerate the group webhook secret (owner) |
| `DELETE` | `/admin/api/groups/:id/webhook` | Admin session | Disable the group webhook ingress (owner) |
| `GET` | `/admin/api/logs` | Admin session | Send logs (scoped) |
| `GET` | `/admin/api/logs/:id` | Admin session | Single send-log entry (scoped) |
| `GET` | `/admin/api/audit` | Admin session | Audit log (scoped to accessible groups) |
| Method | Path | Auth | Description |
|----------|---------------------------------|-------------------|--------------------------------------------------------------------|
| `GET` | `/health` | None | Health check |
| `POST` | `/webhook` | HMAC signature | GitHub / Gitea / custom webhook ingestion (provider auto-detected) |
| `POST` | `/webhook/:groupId` | Per-group secret | Per-group webhook ingress (only that group's routes fire) |
| `POST` | `/discord/interactions` | Ed25519 signature | Discord interactions (slash commands, buttons, modals) |
| `POST` | `/telegram/webhook` | Secret token | Telegram updates (bot `/gh` commands) |
| `GET` | `/api/richheader` | None | Open Graph page for the Telegram avatar link-preview card |
| `GET` | `/auth/github` | None | Start GitHub OAuth flow |
| `GET` | `/auth/github/callback` | None | OAuth callback |
| `GET` | `/auth/github/install` | Admin session | Post-install choice page: bind the installation to a group |
| `POST` | `/auth/github/install/bind` | Admin session | Provision the chosen installation binding |
| `DELETE` | `/auth/token/:userId` | Admin session | Revoke user token |
| `POST` | `/api/comment` | Bearer token | Create issue comment |
| `POST` | `/api/merge` | Bearer token | Merge pull request |
| `POST` | `/api/close` | Bearer token | Close pull request |
| `POST` | `/api/react` | Bearer token | Add reaction to issue |
| `GET` | `/admin` | Admin session | Config console UI |
| `GET` | `/admin/login` | None | Start admin sign-in (GitHub OAuth) |
| `GET` | `/admin/logout` | Admin session | Sign out and destroy the session |
| `GET` | `/admin/invite` | Admin session | Accept a group invite (browser page, `?token=…`) |
The `/admin/api/*` endpoints (routes, groups, members, invites, webhook secrets, send logs, audit log) are documented separately in the [Admin API](./admin).
## Admin Console
See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup. Admin endpoints require a session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS` or manage a group.
- `GET /admin` — Serves the config console HTML
- `GET /admin/api/routes` — Returns `{ "routes": Route[] }`
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id, name, enabled, `groupId`, filters — empty only allowed for `fallback` routes — optional `discordRoleIds` (list of role id strings), and platform-aware targets: `target.channelId` for Discord, `target.chatId` for Telegram) and persists to KV `config:routes`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }` / `403 { error }`.
See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup, and the [Admin API](./admin) reference for all management endpoints. Admin endpoints require a session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS` or manage a group.
## Health Check
@ -81,11 +62,11 @@ Accepts GitHub webhook payloads. Requires valid `X-Hub-Signature-256` header.
**Headers:**
| Header | Required | Description |
|-----------------------|----------|--------------------------------------------------|
| `X-Hub-Signature-256` | Yes | HMAC-SHA256 signature |
| `X-GitHub-Event` | Yes | Event type name |
| `X-GitHub-Delivery` | No | Unique delivery ID (used for dedup when present) |
| Header | Required | Description |
|-------------------------|------------|----------------------------------------------------|
| `X-Hub-Signature-256` | Yes | HMAC-SHA256 signature |
| `X-GitHub-Event` | Yes | Event type name |
| `X-GitHub-Delivery` | No | Unique delivery ID (used for dedup when present) |
**Request Body:** GitHub webhook JSON payload (max 1MB).
@ -101,11 +82,11 @@ When `X-GitHub-Delivery` is present and the same delivery was already processed
**Error Responses:**
| Status | Body | Cause |
|--------|----------------------------------|----------------------------------------|
| `401` | `{"error": "Invalid signature"}` | Signature verification failed |
| `400` | `{"error": "Invalid event"}` | Missing event header or malformed body |
| `413` | `{"error": "Request too large"}` | Body exceeds 1MB limit |
| Status | Body | Cause |
|----------|------------------------------------|------------------------------------------|
| `401` | `{"error": "Invalid signature"}` | Signature verification failed |
| `400` | `{"error": "Invalid event"}` | Missing event header or malformed body |
| `413` | `{"error": "Request too large"}` | Body exceeds 1MB limit |
### Per-Group Webhook (`POST /webhook/:groupId`)
@ -113,18 +94,18 @@ Verifies the payload against the **group's** secret (KV `tenant:{groupId}`, gene
### Custom Webhooks
Any JSON payload signed with `X-WebHooker-Signature: sha256=<hex>` (HMAC-SHA256 of the raw body, group or global secret) becomes a `custom` event. Route it with a route whose filter is `event: custom`. Payload schema: see [Configuration → Custom webhooks](../guide/configuration.md#custom-webhooks).
Any JSON payload signed with `X-WebHooker-Signature: sha256=<hex>` (HMAC-SHA256 of the raw body, group or global secret) becomes a `custom` event. Route it with a route whose filter is `event: custom`. Payload schema: see [Configuration → Custom webhooks](../guide/ingress.md#custom-webhooks).
### GitHub App Installation Events
`installation` webhook events (`created`, ...) are auto-provisioned as a fallback: a group named after the installing account (`inst-{installationId}`, bound via `installationId`) is created automatically, or existing groups whose `owners` match the installing account are bound to the installation. See [Configuration → GitHub App tenant isolation](../guide/configuration.md#github-app-tenant-isolation).
`installation` webhook events (`created`, ...) are auto-provisioned as a fallback: a group named after the installing account (`inst-{installationId}`, bound via `installationId`) is created automatically, or existing groups whose `owners` match the installing account are bound to the installation. See [Configuration → GitHub App tenant isolation](../guide/ingress.md#github-app-tenant-isolation).
The primary flow is the App's **Setup URL** — set it to `{BASE_URL}/auth/github/install`. After a user installs the App, the browser lands on:
| Method | Path | Description |
|--------|-----------------------------|------------------------------------------------------------------------------------------------|
| `GET` | `/auth/github/install` | Choice page: bind the installation to a new group or an existing group the signed-in user owns |
| `POST` | `/auth/github/install/bind` | Provisions the binding (owner role re-checked) and redirects to `/admin?install=ok` |
| Method | Path | Description |
|----------|-------------------------------|--------------------------------------------------------------------------------------------------|
| `GET` | `/auth/github/install` | Choice page: bind the installation to a new group or an existing group the signed-in user owns |
| `POST` | `/auth/github/install/bind` | Provisions the binding (owner role re-checked) and redirects to `/admin?install=ok` |
## Error Format