ReCloudStudio/WebHooker
1
0
Fork 0
mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: align VitePress site with REST send, optional gateway and slash commands

Browse source 
- deployment: drop DISCORD_CHANNEL_ID, add ADMIN_USER_IDS, PKCS#8 key note,
  applications.commands invite scope, and an optional Gateway section
- getting-started: PKCS#8 .dev.vars example, remove channel ID
- introduction: REST delivery, optional DiscordGateway DO, delivery dedup,
  /admin Web UI in architecture and data flow
- index: refresh Workers feature, add Web UI & slash commands feature
This commit is contained in:
RhenCloud 2026-08-02 07:02:40 +08:00
parent f456c979f7
commit d996dbe45d
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
8 changed files with 133 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/guide/introduction.md
View file

@ -1,40 +1,44 @@
# Introduction
WebHooker is a GitHub webhook dispatcher built on Cloudflare Workers. It receives GitHub webhook events, applies configurable filters, formats them into rich Discord embeds, and routes messages to Discord channels or threads via a Durable Object-maintained Gateway connection.
WebHooker is a GitHub webhook dispatcher built on Cloudflare Workers. It receives GitHub webhook events, applies configurable filters, formats them into rich Discord embeds, and delivers them to Discord channels or threads through the Discord REST API. An optional Durable Object holds a Gateway connection to keep the bot online and power the in-Discord `/gh` commands. Routes are managed through a built-in Web UI.
## Architecture
```text
GitHub Webhook → Cloudflare Worker (Hono)
├── POST /webhook → verify → filter → format → DO (Discord Gateway) → Discord
├── POST /webhook → verify → dedup → filter → format → Discord (REST API)
├── GET /auth/github → OAuth flow
├── POST /api/* → user actions (Bearer token auth)
├── /admin → routes & send-log Web UI (admin session)
└── GET /health → status check
(optional) Durable Object ⇄ Discord Gateway → bot online + /gh slash & context commands
```
### Components
| Component | Role |
| ----------------------------------- | --------------------------------------------------------------------------------------------- |
| **Cloudflare Worker** | HTTP ingress, signature verification, event parsing, route matching |
| **Durable Object (DiscordGateway)** | Persistent WebSocket to Discord Gateway, channel cache, message dispatch with retry |
| **KV** | Token storage (`token:{userId}`), OAuth state (`state:{hex}`), route config (`config:routes`) |
| Component | Role |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Cloudflare Worker** | HTTP ingress, signature verification, delivery dedup, event parsing, route matching, REST send |
| **Durable Object (DiscordGateway)** | _Optional._ Keeps the Gateway connection alive (bot online) and handles `/gh` interactions |
| **KV** | Token storage (`token:{userId}`), OAuth state (`state:{hex}`), route config (`config:routes`), send logs, delivery dedup |
### Data Flow
1. GitHub sends a webhook to `POST /webhook`
2. Worker verifies the HMAC-SHA256 signature
3. Worker parses the event type and payload
4. Routes are evaluated against filters (event, repo, actor, action, branch, keyword)
5. Matching routes trigger formatter functions that produce Discord embeds
6. Messages are dispatched to the Durable Object, which maintains the Gateway connection
7. DO sends messages to Discord via REST API with rate-limit retry
3. Worker deduplicates by `X-GitHub-Delivery` (KV, short TTL) to drop repeat deliveries
4. Worker parses the event type and payload
5. Routes are evaluated against filters (event, repo, actor, action, branch, keyword)
6. Matching routes trigger formatter functions that produce Discord embeds
7. Each message is sent to its route's target channel/thread via the Discord REST API with rate-limit retry, and the result is recorded in the send log
## Tech Stack
- **Runtime**: Cloudflare Workers
- **HTTP Framework**: Hono
- **Discord Gateway**: Durable Object (persistent WebSocket + channel cache)
- **Discord delivery**: Discord REST API (Gateway via optional Durable Object for online status + `/gh` commands)
- **Web UI**: Nuxt 3 static SPA served from Worker assets
- **Storage**: Cloudflare KV
- **Auth**: Web Crypto API (HMAC-SHA256), jose (JWT), octokit (GitHub API)
- **Language**: TypeScript