Files
WebHooker/docs/api/admin.md
T
翅膀 5fcb129170 docs(worker): align guides with runtime behavior
Synchronize both language guides, API references and examples with
the implemented authorization, storage and delivery behavior.
Document migration requirements and accepted operational limits.
2026-10-23 23:24:05 +08:00

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 for fallback routes or when a valid ast is present; patterns the matcher cannot compile — longer than 200 characters, or RE2-unsupported syntax such as backreferences or lookaround — are rejected; flat filters hold leaf conditions only (all/any/not belong in ast); keyword only supports the default eq; exists may omit match — optional discordRoleIds (at most 50 numeric Discord role ids), and platform-aware targets: target.channelId for Discord, target.chatId for Telegram/Feishu, with the id rules and duplicate-destination check in Routes & Targets) and persists to D1 d1_routes, rewriting only the groups whose routes changed. A non-super admin pointing a target at a channel another group uses gets 403. Returns 200 { ok, count } or 400 { error } / 401 { error } / 403 { error }. Unchanged routes skip the full validation. Route filters support the field type (a JSONPath path into payload, arrays expand so any element matches) and 12 op operators (eq default / ne / contains / startsWith / endsWith / regex / gt / gte / lt / lte / in / exists); a nested ast (all / any / not) takes precedence over filters when present.
  • PUT /admin/api/groups / POST /admin/api/groups / PUT /admin/api/groups/:id — Validate group ids, members (or legacy adminIds; a non-empty members list needs at least one owner), forgeSources (at most 20, name up to 50 characters, unique type + host), providers (github / gitea / custom), and installationId; unknown fields are dropped. The source-isolation fields owners, installationId and isolated are 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 (409 for route/fragment writes, 403 for group writes).
  • Optimistic concurrency — every list or group the API returns carries a revision. Send it back with the write (group.revision, or revision next to routes / fragments / newId, or the list revision of the bulk groups write) and the server refuses the write with 409 if the stored data changed since it was loaded, instead of overwriting the newer change. Writes without a revision are applied as before. In the bulk groups write, a group echoed back unedited is never written.
  • PUT /admin/api/groups/:id/routes — Optional discardUnreadable: true replaces stored routes that cannot be read (otherwise the save is refused while the group has any).
  • PUT /admin/api/routes — Optionally send revisions (the per-group map returned by GET /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 (409 otherwise). Each group is written in its own guarded transaction.
  • PUT /admin/api/groups/:id/rename — Optional revision; returns { ok, id, group, revision } (the renamed group and its new revision). Ids starting with inst- or u- are reserved for super admins.
  • DELETE /admin/api/groups/:id — Requires revision, routesRevision and version as seen at confirmation (400 when missing, 409 when 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 D1 d1_fragments; the editor inlines a fragment's node into a route's ast on insert (the matcher never resolves fragment references). PUT replaces the group's fragments (at most 200) and returns 200 { 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.