mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00

wyf9 afe19795b1

docs: sync documentation with current codebase

- Update event formatter count 23 -> 28 (add ping, workflow_job, status, deployment, check_suite)
- Document Telegram support end-to-end (routes, /gh commands, richheader, secrets)
- Fix route schema to use targets array and group fields (owners, emoji)
- Correct KV/D1 storage layout (msg:*, i18n:*, D1 links/send_logs)
- Note GITHUB_APP_ID/GITHUB_PRIVATE_KEY are unused; drop legacy DISCORD_CHANNEL_ID/PORT/CONFIG_PATH
- Remove stale Docker deployment section
- Update color table, branch filter compatibility, admin API endpoints
- AGENTS.md: add Documentation section requiring doc updates after functional changes

2026-08-05 17:22:15 +08:00

5.3 KiB

Raw Blame History

API Overview

WebHooker exposes an HTTP API via Hono on Cloudflare Workers.

Base URL

https://your-worker.workers.dev

Endpoints

Method	Path	Auth	Description
`GET`	`/health`	None	Health check
`POST`	`/webhook`	HMAC signature	GitHub webhook ingestion
`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
`DELETE`	`/auth/token/:userId`	None	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/api/routes`	Admin session	List routes
`PUT`	`/admin/api/routes`	Admin session	Replace routes
`GET`	`/admin/api/groups`	Admin session	List groups (scoped)
`PUT`	`/admin/api/groups`	Admin session	Replace groups (super)
`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
`GET`	`/admin/api/me`	Admin session	Current session info
`GET`	`/admin/api/logs`	Admin session	Send logs (scoped)
`GET`	`/admin/api/logs/:id`	Admin session	Single send-log entry (scoped)

Admin Console

See Configuration → 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 — 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 }.

Health Check

GET /health

Response:

{
  "status": "ok"
}

Webhook Ingestion

POST /webhook

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)

Request Body: GitHub webhook JSON payload (max 1MB).

Response:

{
  "ok": true
}

When X-GitHub-Delivery is present and the same delivery was already processed within the last 5 minutes, the worker responds 200 { "ok": true, "duplicate": true } without re-dispatching.

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

Error Format

All error responses follow the format:

{
  "error": "Description of the error"
}

5.3 KiB Raw Blame History