mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
13 KiB
13 KiB
Admin API
Admin endpoints manage routes, groups, members, invites, webhook secrets, send logs, and the audit log. They require an admin session cookie obtained via GET /admin/login (GitHub OAuth); the signed-in user must be listed in ADMIN_USER_IDS or manage a group. For local development only, exact DEBUG_MODE=true bypasses authentication and grants full access; never deploy with it enabled. See Configuration → Web UI for setup.
The console itself is served at /admin; its tabs are deep-linkable via the URL path (/admin/groups, /admin/logs, /admin/audit).
Endpoints
| Endpoint | Description |
|---|---|
GET /admin |
Config console UI |
GET /admin/login |
Start admin sign-in (GitHub OAuth) |
GET /admin/logout |
Sign out and destroy the session |
GET /admin/invite?token=… |
Accept a group invite (browser page) |
GET /admin/api/me |
Current session, scope, groups, and roles |
GET /admin/api/routes |
List routes (scoped to access) |
PUT /admin/api/routes |
Replace routes (owner/admin per group) |
GET /admin/api/groups |
List groups (each with its revision) + the signed-in user's role in each, plus the list revision |
PUT /admin/api/groups |
Bulk write (legacy): super admins replace all groups, owners change/delete their own; only groups that differ are written |
POST /admin/api/groups |
Create one group (super admins) — body { group }; 409 when the id exists or was used recently |
PUT /admin/api/groups/:id |
Update one group (owner) — body { group }; 409 when its revision is stale |
DELETE /admin/api/groups/:id |
Delete one group with its routes and fragments (owner) — query revision, routesRevision and version from the confirmation; 409 when anything changed since |
GET /admin/api/groups/:id/routes |
List a group's routes, with the list's revision, the group version and unreadable |
PUT /admin/api/groups/:id/routes |
Replace a group's routes (owner/admin) — 409 when the sent revision is stale |
GET /admin/api/groups/:id/fragments |
List a group's named filter fragments, with the list's revision |
PUT /admin/api/groups/:id/fragments |
Replace a group's named filter fragments (owner/admin) — body { fragments, revision? }; 409 when the revision is stale |
PUT /admin/api/groups/:id/rename |
Rename a group (owner) — body { newId, revision? }; routes, fragments and history move in one transaction, the secret and invites stay with the group; the old id stays retired for a few days |
GET /admin/api/groups/:id/invites |
List pending invites (owner) |
POST /admin/api/groups/:id/invites |
Create an invite link (owner) — body { role, note? } (role is admin or viewer) |
DELETE /admin/api/invites/:token |
Revoke an invite (owner) |
GET /admin/api/groups/:id/webhook |
Group webhook endpoint info (owner) |
POST /admin/api/groups/:id/webhook/regenerate |
Generate/regenerate the group webhook secret (owner) |
DELETE /admin/api/groups/:id/webhook |
Disable the group webhook ingress (owner) |
GET /admin/api/logs |
Send logs of the accessible groups (filtered in SQL before the limit) |
GET /admin/api/logs/:id |
Single send-log entry (scoped) |
GET /admin/api/audit |
Audit log of the accessible groups (filtered in SQL before the limit) |
GET /admin/api/metrics |
Delivery stats (totals, failure rate, per platform/event/status, recent failures); optional ?groupId= scope; every aggregate is limited to the accessible groups |
GET /admin/api/delivery/:deliveryId |
The attempts of one delivery that belong to the accessible groups; optional ?groupId= (two groups' senders may use the same delivery id) |
POST /admin/api/test-match |
Stateless filter dry-run — evaluate a filter node against a pasted JSON payload (no event is stored) |
Validation
PUT /admin/api/routes— Body{ "routes": Route[] }; validates each route (id pattern, unique id within its group, name, enabled,groupId, filters — an array, empty only forfallbackroutes or when a validastis present; patterns the matcher cannot compile — longer than 200 characters, or RE2-unsupported syntax such as backreferences or lookaround — are rejected; flatfiltershold leaf conditions only (all/any/notbelong inast);keywordonly supports the defaulteq;existsmay omitmatch— optionaldiscordRoleIds(at most 50 numeric Discord role ids), and platform-aware targets:target.channelIdfor Discord,target.chatIdfor Telegram/Feishu, with the id rules and duplicate-destination check in Routes & Targets) and persists to D1d1_routes, rewriting only the groups whose routes changed. A non-super admin pointing a target at a channel another group uses gets403. Returns200 { ok, count }or400 { error }/401 { error }/403 { error }. Unchanged routes skip the full validation. Route filters support thefieldtype (a JSONPathpathintopayload, arrays expand so any element matches) and 12opoperators (eqdefault /ne/contains/startsWith/endsWith/regex/gt/gte/lt/lte/in/exists); a nestedast(all/any/not) takes precedence overfilterswhen present.PUT /admin/api/groups/POST /admin/api/groups/PUT /admin/api/groups/:id— Validate group ids,members(or legacyadminIds; a non-emptymemberslist needs at least oneowner),forgeSources(at most 20,nameup to 50 characters, unique type + host),providers(github/gitea/custom), andinstallationId; unknown fields are dropped. The source-isolation fieldsowners,installationIdandisolatedare super-admin only: an owner's write keeps their stored values. New members' logins are resolved to GitHub user ids with the writer's token; the server-only fields (instance, the webhook secret, member user ids) can never be set by the client.- Every write re-checks the writer's role inside its transaction: a request authorized before the role was revoked is refused (
409for route/fragment writes,403for group writes). - Optimistic concurrency — every list or group the API returns carries a
revision. Send it back with the write (group.revision, orrevisionnext toroutes/fragments/newId, or the listrevisionof the bulk groups write) and the server refuses the write with409if the stored data changed since it was loaded, instead of overwriting the newer change. Writes without arevisionare applied as before. In the bulk groups write, a group echoed back unedited is never written. PUT /admin/api/groups/:id/routes— OptionaldiscardUnreadable: truereplaces stored routes that cannot be read (otherwise the save is refused while the group has any).PUT /admin/api/routes— Optionally sendrevisions(the per-group map returned byGET /admin/api/routes): groups whose list comes back unedited are not written, groups the client never loaded are not touched, and edited groups must still be at their loaded revision (409otherwise). Each group is written in its own guarded transaction.PUT /admin/api/groups/:id/rename— Optionalrevision; returns{ ok, id, group, revision }(the renamed group and its new revision). Ids starting withinst-oru-are reserved for super admins.DELETE /admin/api/groups/:id— Requiresrevision,routesRevisionandversionas seen at confirmation (400when missing,409when the group, its routes or fragments changed, or when it has routes that cannot be read). Also revokes the group's invites and webhook secret, detaches its send logs and audit entries (they stay visible to super admins only), and retires the id for a few days so queued deliveries cannot reach a new group that reuses it.POST /admin/api/groups/:id/webhook/regenerate— Returns{ ok, url, secret, hasSecret }; the secret is shown only in this response.POST /admin/api/test-match— Body{ "node": FilterNode | "filters": Filter[], "event"?: string, "payload": object }; evaluates in memory and returns{ matched, explanation }. Nothing is persisted.GET/PUT /admin/api/groups/:id/fragments— Named filter fragments ({ id, groupId, name, node }) stored in D1d1_fragments; the editor inlines a fragment'snodeinto a route'saston insert (the matcher never resolves fragment references).PUTreplaces the group's fragments (at most 200) and returns200 { ok, count }.- Limits: one save accepts at most 200 routes, 200 fragments per group, and 100 groups in the bulk groups write.
Schemas: Routes & Targets, Groups & Access Control.