12 KiB
Configuration
This page is the reference for secrets and the Web UI. Core concepts live in dedicated pages:
| Topic | Page |
|---|---|
Routes, targets, fallback / stop, role pings |
Routes & Targets |
| Groups, roles, invites, self sign-up, log channel | Groups & Access Control |
| Webhook providers, per-group ingress, custom | Webhook Ingress & Tenancy |
| KV / D1 key layout | Storage Layout |
| Filters (pattern syntax reference) | Filter Types below / Filter Tutorial |
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 |
GITEA_WEBHOOK_SECRET |
Webhook secret from your Gitea instance (only to receive Gitea webhooks) |
GITHUB_CLIENT_ID |
OAuth client ID from App settings |
GITHUB_CLIENT_SECRET |
OAuth client secret from App settings |
DISCORD_TOKEN |
Discord bot token |
TELEGRAM_TOKEN |
Telegram bot token (from BotFather) — required for Telegram routes |
FEISHU_APP_ID |
Feishu app ID (from the app Credentials page) — required for Feishu routes |
FEISHU_APP_SECRET |
Feishu app secret — required for Feishu routes |
Important
Inbound Feishu commands and card buttons (
POST /feishu/webhook) requireFEISHU_ENCRYPT_KEYand/orFEISHU_VERIFICATION_TOKEN(the app's Events & Callbacks → Encryption Strategy values). Without either, the endpoint refuses every callback, since an unauthenticated request could act as any linked user.
Note
GITHUB_APP_IDandGITHUB_PRIVATE_KEY(PKCS#8 PEM) are used by the GitHub App install flow (/auth/github/install) to resolve the installation's account via an App JWT — which is also how the flow verifies that the signed-in user may manage the installation. Without them only super admins can bind installations. The OAuth flow itself only needsGITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET; it requests therepoandread:orgscopes (the latter to check organization admin rights).
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 |
TELEGRAM_WEBHOOK_SECRET |
Secret token for POST /telegram/webhook verification (X-Telegram-Bot-Api-Secret-Token) |
Derived from TELEGRAM_TOKEN |
FEISHU_ENCRYPT_KEY |
Feishu event Encrypt Key: verifies X-Lark-Signature and decrypts encrypted callbacks |
Unset |
FEISHU_VERIFICATION_TOKEN |
Feishu event Verification Token, compared with the token in every callback | Unset |
TELEGRAM_RICH_HEADER_HOST |
Base URL of an external rich-header service; when unset, the built-in GET /api/richheader serves the Telegram avatar card |
Built-in /api/richheader |
BASE_URL |
Public URL of the worker, for OAuth callbacks and the Telegram webhook sync | Unset — required in production |
ADMIN_USER_IDS |
Comma-separated GitHub user IDs (or logins) allowed to access the Web UI; prefer numeric ids — a login is bound to the first account that signs in with it | Disabled |
DEBUG_MODE |
Local development only: exact true bypasses all /admin authentication and grants full access |
Disabled |
ALLOW_SELF_SIGNUP |
When enabled (1/true), GitHub users without any group access get an isolated personal group on first login instead of 403 |
Disabled |
AUDIT_RETENTION_DAYS |
Audit-log retention in days for the scheduled cleanup | 90 |
DELIVERY_STATE_STORE |
Where webhook delivery state lives: d1 (default) or kv. KV answers at the edge but the free plan allows only ~1,000 writes/day — see Storage decisions |
d1 |
NUXT_PUBLIC_DOCS_URL |
Docs site URL used by the landing page (client-side runtime config) | Landing page defaults |
NUXT_PUBLIC_REPO_URL |
GitHub repo URL used by the landing page | Landing page defaults |
NUXT_PUBLIC_LEGAL_CONTACT |
Contact shown on /terms and /privacy |
Unset → placeholder text |
Web UI
WebHooker ships with a built-in config console at /admin for managing routes, groups, members, invites, send logs, and the audit log in the browser. It is protected by GitHub OAuth plus an admin whitelist.
Setup
- Configure
ADMIN_USER_IDSwith the GitHub user IDs allowed to manage everything. Logins are also accepted, e.g.ADMIN_USER_IDS=12345,RhenCloud, but numeric ids are safer: GitHub logins can be renamed and re-registered, so a login is bound to the first account that signs in with it. If unset, there are no super admins: members of a group still reach the console for their groups, andALLOW_SELF_SIGNUPgives other users a personal group. - Open
/adminand sign in with GitHub. - Users without any access get
403, except whenALLOW_SELF_SIGNUP=1(they receive a personal group) or when they follow a group invite link.
For local debugging only, set DEBUG_MODE=true to bypass GitHub OAuth and grant complete console access. Do not set this variable in a deployed environment.
The console is served as an SPA at /admin; its tabs are deep-linkable via the URL path (/admin/groups, /admin/logs, /admin/audit), and each group's routes page has its own URL (/admin/groups/{groupId}). Pages are browser history entries: use the browser's (or device's) back button to return from a group to the group list; leaving a page with an open editor or an unsaved route order asks for confirmation first. Unknown console paths return the console's 404 page. URLs outside /admin that do not match an endpoint return a plain 404 instead of the console.
Destructive actions — deleting routes, groups, filter conditions, fragments, targets or forge hosts, removing members, revoking invites, disabling a group's webhook — ask for confirmation in an in-app dialog (empty, never-filled rows are removed directly). The route and group editors ignore clicks on the backdrop so unsaved input is never lost; close them with Cancel, ✕ or Esc.
All management endpoints (/admin/api/*) are documented in the Admin API. Saved routes and groups are persisted to D1 (d1_routes / d1_groups) immediately; webhook ingress and the queue consumer read the configuration fresh, so the next event already uses them.
Filter Types
See the Filter Tutorial for a hands-on guide with worked examples.
| Type | Matches | Example |
|---|---|---|
event |
GitHub event name | push, pull_*, pull_request |
repo |
Repository full name | org/repo, org/* |
actor |
Sender login | username, [bot], *[bot] |
action |
Event action | opened, closed, published |
branch |
Branch name | main, feature-?, /^release-/ |
field |
Any payload field (JSONPath) | path: "pull_request.user.login" |
keyword |
Text in payload body | deploy, /fix\s+\d+/ |
Filter Behavior
- All filters in a route must match for the route to trigger (AND logic)
- Set
"exclude": trueon any filter to invert it (NOT logic) - Every filter type supports the same pattern forms: plain text,
*/?globs (*= any run,?= one character), and/regular expression/— all case-insensitive - Field filters (
event/repo/actor/action/branch/field) glob-match the whole value;keywordglobs and regexes search anywhere in the payload; plainkeywordtext is a substring search - Every filter except
keyword(which only supports the defaulteq) accepts anopoperator —eq(default, classic behaviour),ne,contains,startsWith,endsWith,regex,gt,gte,lt,lte,in,exists— see the Filter Tutorial fieldfilters use a dot-separated JSONPathpathinto the payload; arrays are expanded so any matching element satisfies the filter- Routes may nest filters in an
astnode (all/any/not) instead of a flatfilterslist;asttakes precedence when present - Globs and regexes run on the RE2 engine (linear time). A pattern the matcher cannot compile — longer than 200 characters, or using syntax RE2 lacks such as backreferences or lookaround — is rejected when saved; one stored before makes its route unreadable instead of silently never matching
branchfilter works for push, pull_request, pull_request_review, pull_request_review_comment, create/delete, workflow_run, workflow_job, check_run, check_suite, deployment, deployment_status, 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"] }
{ "type": "field", "path": "pull_request.commits", "op": "gt", "match": "1" }