WebHooker/docs/guide/configuration.md

Configuration

Secrets

WebHooker requires several secrets to function. For local development, store them in .dev.vars. For production, use Cloudflare Worker Secrets.

Required Secrets

Variable	Description
GITHUB_WEBHOOK_SECRET	Webhook secret from your GitHub App settings
GITHUB_APP_ID	Numeric ID of your GitHub App
GITHUB_PRIVATE_KEY	App private key (PEM format, with \n escapes)
GITHUB_CLIENT_ID	OAuth client ID from App settings
GITHUB_CLIENT_SECRET	OAuth client secret from App settings
DISCORD_TOKEN	Discord bot token

Optional Secrets

Variable	Description	Default
DISCORD_PUBLIC_KEY	Discord application public key (Developer Portal) — required for interactions	Unset → interactions return 401
DISCORD_APPLICATION_ID	Discord application id; auto-resolved when omitted	Auto-resolved
BASE_URL	Public URL for OAuth callbacks	http://localhost:8787
ADMIN_USER_IDS	Comma-separated GitHub user IDs (or logins) allowed to access the Web UI	Disabled

Web UI

WebHooker ships with a built-in config console at /admin for managing routes in the browser. It is protected by GitHub OAuth plus an admin whitelist.

Setup

1. Configure ADMIN_USER_IDS with the GitHub user IDs allowed to manage routes. Logins are also accepted, e.g. ADMIN_USER_IDS=12345,RhenCloud. If unset, the console is disabled.
2. Open /admin and sign in with GitHub.
3. Only users in the whitelist receive a session cookie; everyone else gets 403.

Endpoints

Endpoint	Description
GET /admin	Config console UI
GET /admin/login	Start GitHub OAuth sign-in
GET /admin/logout	Destroy session
GET /admin/api/me	Current session, scope, and groups
GET /admin/api/routes	List routes (admin only)
PUT /admin/api/routes	Replace routes (admin only)
GET /admin/api/groups	List groups (scoped to access)
PUT /admin/api/groups	Replace groups (super admin only)
GET /admin/api/groups/:id/routes	List a group's routes
PUT /admin/api/groups/:id/routes	Replace a group's routes
GET /admin/api/logs	Send logs (scoped to accessible routes)

The console lets you add, edit, delete, and toggle routes. Saved routes are written to KV config:routes immediately and the config cache is invalidated so the webhook pipeline picks them up on the next run.

Routes

Routes define which events get forwarded to which Discord channels. They are stored in Cloudflare KV under the key config:routes as a JSON array.

There are no default routes — each route must define its own target. If no routes are configured, no events are forwarded.

Route Schema

{
  "id": "unique-route-id",
  "name": "Human-readable name",
  "enabled": true,
  "groupId": "my-group",
  "fallback": false,
  "filters": [
    { "type": "event", "match": "push" },
    { "type": "repo", "match": "org/repo", "exclude": false }
  ],
  "target": {
    "channelId": "REQUIRED_CHANNEL_ID",
    "threadId": "OPTIONAL_THREAD_ID"
  }
}

target.channelId is required and used as-is; there is no fallback to a default channel.

Other route fields:

Field	Type	Required	Description
groupId	string	Yes	Id of the group this route belongs to
fallback	boolean	No	When true, fires only if no non-fallback route matched the event; its own filters are ignored
lang	string	No	Message language override for this route (e.g. en, zh); defaults to the global setting

Custom Route Example

[
  {
    "id": "backend-prs",
    "name": "Backend PRs",
    "enabled": true,
    "groupId": "backend-team",
    "filters": [
      { "type": "repo", "match": "myorg/backend" },
      { "type": "event", "match": "pull_request" },
      { "type": "actor", "match": "[bot]", "exclude": true }
    ],
    "target": {
      "channelId": "1234567890",
      "threadId": "9876543210"
    }
  }
]

Groups

Routes belong to groups. Groups scope admin access and can restrict which events flow into them. They are stored in Cloudflare KV under the key config:groups as a JSON array.

Group Schema

{
  "id": "backend-team",
  "name": "Backend Team",
  "adminIds": ["rhencloud"],
  "owners": ["myorg"]
}

Field	Type	Required	Description
id	string	Yes	Lowercase id (a-z0-9, -); referenced by each route's groupId
name	string	Yes	Human-readable group name
adminIds	string[]	Yes	GitHub user IDs or logins who may manage this group's routes
owners	string[]	No	Org/user logins whose events are accepted into this group; empty = all

Access Model

• Super admins (ADMIN_USER_IDS) see and edit every group and all routes.
• Group admins (adminIds) only see and edit the groups they manage; submitting a route outside their groups returns 403.
• Group admin endpoints operate on a single group at a time via /admin/api/groups/:id/routes; groupId is forced from the path parameter.
• The owners list restricts which event actors (sender logins) the group's routes will dispatch at all.

Filter Types

See the Filter Tutorial for a hands-on guide with worked examples.

Type	Matches	Example
event	GitHub event name	push, pull_request, issues
repo	Repository full name	org/repo
actor	Sender login	username, [bot]
action	Event action	opened, closed, published
branch	Branch name	main, develop
keyword	Text in payload body	deploy, /fix\s+\d+/ (regex)

Filter Behavior

• All filters in a route must match for the route to trigger (AND logic)
• Set "exclude": true on any filter to invert it (NOT logic)
• Non-keyword filters are exact, case-insensitive matches — no wildcards (repo: "org/*" does not match anything)
• keyword filter supports regex patterns — falls back to substring match if regex is invalid or longer than 200 characters
• branch filter works for push, pull_request, pull_request_review, pull_request_review_comment, create/delete, workflow_run, and code_scanning_alert events

Match Values

Filters accept either a single string or an array of strings:

{ "type": "event", "match": "push" }
{ "type": "event", "match": ["push", "pull_request"] }

KV Storage Layout

Key Pattern	Value	TTL
config:routes	JSON array of routes	Permanent
config:groups	JSON array of groups	Permanent
session:{id}	Admin session { userId, login }	7 days
token:{userId}	{ userId, accessToken, expiresAt, refreshToken? }	0.9 × token expiry
token-reverse:{sha256}	User id for reverse lookup by token	0.9 × token expiry
discord-link:{userId}	GitHub user id linked to a Discord user	Permanent
state:{hex}	{ redirectTo, expiresAt, discordUserId? }	600 seconds
delivery:{id}	Webhook delivery id (dedup marker)	300 seconds
cmd:guild:{id}	Guild id whose commands were registered (dedup)	Permanent
cmd:registered:global	Global command registration marker (dedup)	1 day
config:discord-app-id	Cached Discord application id	Permanent
logs:send:{ts}-{hex}	Send record	1 hour