diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 161 |
1 files changed, 67 insertions, 94 deletions
@@ -4,8 +4,8 @@ A simple API service for receiving and storing webhook requests with dynamic rou ## Features -- Dynamic route/topic registration -- Multiple content type support (JSON, form, text, raw) +- File-based route configuration with hot-reload +- Multiple content type support (JSON, form, text, raw, multipart) - CSRF token protection with HMAC-signed stateless tokens - hCaptcha protection per route - ntfy notification alerts when webhooks are received @@ -16,83 +16,70 @@ A simple API service for receiving and storing webhook requests with dynamic rou - Comprehensive metrics and tracing - Single Dockerfile deployment -## API Endpoints - -### Route Prefixes - -- **`/`** - Public routes (webhooks, token generation, health) -- **`/admin`** - Admin routes (route management) - Put behind OAuth proxy - -### Admin Endpoints - -**⚠️ Recommendation**: Put `/admin/*` behind an OAuth proxy (e.g., OAuth2 Proxy, Pomerium) for authentication. - -#### Register a Route - -```bash -POST /admin/routes -Content-Type: application/json - -{ - "name": "my-webhook", - "contentType": "json", - "hcaptchaProtected": false -} -``` - -With hCaptcha protection: - -```bash -POST /admin/routes -Content-Type: application/json - -{ - "name": "protected-webhook", - "contentType": "json", - "hcaptchaProtected": true, - "hcaptchaSecret": "your-hcaptcha-secret" -} -``` - -With ntfy notifications: - -```bash -POST /admin/routes -Content-Type: application/json +## Configuration -{ - "name": "notified-webhook", - "contentType": "json", - "hcaptchaProtected": false, - "ntfy": { - "enabled": true, - "server": "https://ntfy.sh", - "topic": "my-webhook-alerts" - } -} +Routes are configured via a `routes.toml` file that Posthook watches for changes. When you edit the file, Posthook automatically reloads the configuration. + +### Example Configuration + +Create a `routes.toml` file: + +```toml +# Simple JSON webhook +[[route]] +name = "github-webhook" +contentType = "json" +hcaptchaProtected = false +requireToken = false + +# Form with hCaptcha protection +[[route]] +name = "contact-form" +contentType = "form" +hcaptchaProtected = true +hcaptchaSecret = "0x0000000000000000000000000000000000000000" +requireToken = false + +# JSON webhook with ntfy notifications +[[route]] +name = "alerts" +contentType = "json" +hcaptchaProtected = false +requireToken = false + +[route.ntfy] +enabled = true +server = "https://ntfy.sh" +topic = "my-alerts" + +# Multipart file upload with token protection +[[route]] +name = "file-upload" +contentType = "multipart" +hcaptchaProtected = false +requireToken = true ``` -With CSRF token protection: +### Configuration Fields -```bash -POST /admin/routes -Content-Type: application/json - -{ - "name": "secure-form", - "contentType": "form", - "hcaptchaProtected": false, - "requireToken": true -} -``` +- `name` - Route identifier (alphanumeric, dash, underscore only) +- `contentType` - One of: `json`, `form`, `multipart`, `text`, `raw` +- `hcaptchaProtected` - Enable hCaptcha verification (default: false) +- `hcaptchaSecret` - hCaptcha secret key (required if hcaptchaProtected is true) +- `requireToken` - Enable CSRF token protection (default: false) +- `ntfy` - Optional ntfy notification configuration: + - `enabled` - Enable notifications (required) + - `server` - ntfy server URL (required if enabled) + - `topic` - ntfy topic name (required if enabled) -#### List Routes +### Hot Reload -```bash -GET /admin/routes -``` +Posthook watches `routes.toml` for changes. When you save the file: +- Valid changes are applied immediately +- Invalid configuration causes the process to exit (fail-fast) +- No need to restart the server for route updates -### Public Webhook Endpoints +## API Endpoints #### Get CSRF Token (for routes with requireToken: true) @@ -347,37 +334,23 @@ docker run -p 9000:9000 \ posthook ``` -### With OAuth Proxy (Recommended for Production) - -Protect admin routes with an OAuth proxy: +### With Custom Config Location ```bash -# Run posthook -docker run -p 9000:9000 posthook - -# Run OAuth2 Proxy in front of /admin routes -docker run -p 4180:4180 \ - quay.io/oauth2-proxy/oauth2-proxy:latest \ - --upstream=http://localhost:9000/admin \ - --http-address=0.0.0.0:4180 \ - --provider=google \ - --client-id=your-client-id \ - --client-secret=your-client-secret \ - --cookie-secret=random-secret-here \ - --email-domain=yourdomain.com +docker run -p 9000:9000 \ + -v $(pwd)/my-routes.toml:/app/routes.toml \ + -v $(pwd)/data:/app/data \ + -e POSTHOOK_TOKEN_SECRET=your-secret-here \ + posthook -- --config /app/routes.toml ``` -Then configure your reverse proxy: - -- `/admin/*` → OAuth2 Proxy on port 4180 -- `/` → Posthook on port 9000 - -## Configuration +## Runtime Configuration ### Command Line Arguments: - `--port` - Server port (default: 9000) - `--host` - Server host (default: 0.0.0.0) +- `--config` - Path to routes.toml configuration file (default: ./routes.toml) - `--data-dir` - Data storage directory (default: ./data) - `--token-secret` - HMAC secret for token signing (optional, generates random if not provided) - `--cors-origins` - Allowed CORS origins (default: `*`). Supports `*`, exact origins (`https://a.com`), and host patterns (`liz.coffee`, `*.liz.coffee`). When not `*`, only `https` origins are allowed. Responses only set `Access-Control-Allow-Origin` (preflight uses the standard allow-\* headers). |