path: root/README.md

# Posthook - Dynamic Webhook Receiver

A simple API service for receiving and storing webhook requests with dynamic route registration.

## Features

- Dynamic route/topic registration
- Multiple content type support (JSON, form, text, raw)
- CSRF token protection with HMAC-signed stateless tokens
- hCaptcha protection per route
- ntfy notification alerts when webhooks are received
- Form redirect support (`_redirect` field)
- Request storage with timestamp-prefixed UUIDs
- Per-topic storage organization
- TypeScript with Pengueno framework
- 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

{
  "name": "notified-webhook",
  "contentType": "json",
  "hcaptchaProtected": false,
  "ntfy": {
    "enabled": true,
    "server": "https://ntfy.sh",
    "topic": "my-webhook-alerts"
  }
}
```

With CSRF token protection:

```bash
POST /admin/routes
Content-Type: application/json

{
  "name": "secure-form",
  "contentType": "form",
  "hcaptchaProtected": false,
  "requireToken": true
}
```

#### List Routes

```bash
GET /admin/routes
```

### Public Webhook Endpoints

#### Get CSRF Token (for routes with requireToken: true)

```bash
GET /hook/{routeName}/token
```

Response:

```json
{
    "ok": {
        "token": "eyJ0aW1lc3RhbXAiOjE3MDI4MzQ1Njc4OTB5...",
        "expiresAt": 1702835467890
    }
}
```

**Note**: Tokens expire in **30 seconds**. Generate the token server-side when rendering your form, not via client-side fetch.

#### Send Webhook

Send webhooks to registered routes:

```bash
POST /hook/{routeName}
Content-Type: application/json

{
  "your": "data"
}
```

For hCaptcha-protected routes, include the token:

```bash
POST /hook/{routeName}
H-Captcha-Response: <token>
Content-Type: application/json

{
  "your": "data"
}
```

For form submissions with redirect (returns 303 redirect instead of JSON):

```bash
POST /hook/{routeName}
Content-Type: application/x-www-form-urlencoded

name=John&email=john@example.com&_redirect=https://example.com/thank-you
```

Or in HTML:

```html
<form action="/hook/my-form" method="POST">
    <input type="text" name="name" required />
    <input type="email" name="email" required />
    <input type="hidden" name="_redirect" value="https://example.com/thank-you" />
    <button type="submit">Submit</button>
</form>
```

For token-protected routes, include the token:

```bash
POST /hook/{routeName}
X-CSRF-Token: <token>
Content-Type: application/json

{
  "your": "data"
}
```

Or in form data:

```bash
POST /hook/{routeName}
Content-Type: application/x-www-form-urlencoded

name=John&email=john@example.com&_token=<token>
```

#### Health Check

```bash
GET /health
```

## Content Types

- `json` - Parse request body as JSON
- `form` - Parse as URL-encoded form data (supports `_redirect` field)
- `text` - Store as plain text
- `raw` - Store raw body
- `multipart` - Multipart form data (supports file uploads and `_redirect`)

## CSRF Token Protection

Posthook supports stateless CSRF token protection using HMAC-signed tokens. When `requireToken: true` is set on a route, clients must include a valid token with their request.

### How it works:

1. **Token Generation**: Tokens are HMAC-signed with a secret and contain:
    - Route name (prevents token reuse across routes)
    - Timestamp (30-second TTL)

2. **Token Delivery**: Tokens can be provided via:
    - `_token` field in form data (extracted and not stored)
    - `X-CSRF-Token` request header

3. **Validation**: Server validates:
    - HMAC signature
    - Route name matches
    - Token not expired (30 seconds)
    - Timestamp not from future

### Token Secret Configuration:

```bash
# Via environment variable (recommended for production)
export POSTHOOK_TOKEN_SECRET=your-long-random-secret-here
npm start

# Via command line
npm start -- --token-secret your-long-random-secret-here

# Auto-generated (not recommended - changes on restart)
npm start  # Warns and generates random secret
```

### Server-Side Token Generation (Recommended):

With a 30-second TTL, you should generate the token server-side when rendering the form, not via client-side JavaScript.

**Example with server-side rendering**:

```html
<!-- Your server fetches the token before rendering -->
<form action="/hook/contact-form" method="POST">
    <input type="hidden" name="_token" value="<%= token %>" />
    <input type="text" name="name" required />
    <input type="email" name="email" required />
    <input type="hidden" name="_redirect" value="/thanks" />
    <button type="submit">Submit</button>
</form>
```

**Your server** (Node.js example):

```javascript
app.get('/contact', async (req, res) => {
    const response = await fetch('http://localhost:9000/hook/contact-form/token');
    const {
        ok: { token },
    } = await response.json();
    res.render('contact', { token });
});
```

## Form Redirects

When using `contentType: "form"` or `contentType: "multipart"`, you can include a `_redirect` field in your form data. If the request is successfully stored, the server will respond with a `303 See Other` redirect to the specified URL instead of a JSON response.

The `_redirect` field is:

- Extracted from the form data and not stored in the request body
- Only honored on successful requests (validation failures, errors, etc. will still return JSON error responses)
- Useful for traditional HTML form submissions where you want to redirect users after submission

Example form flow:

1. User submits form with `_redirect` field (and `_token` if required)
2. Posthook validates token (if required) and stores the request
3. Posthook sends ntfy notification (if configured)
4. Posthook responds with `303 See Other` and `Location: {redirect_url}` header
5. Browser automatically redirects user to the specified URL

## ntfy Notifications

When you register a route with ntfy enabled, posthook will send a notification to your specified ntfy server and topic whenever a webhook is received. The notification includes:

- Request timestamp
- Request UUID
- HTTP method
- Route name

Example notification:

```
Title: Webhook received: my-webhook
Message: Method: POST
Timestamp: 2024-12-14T19:30:45.123Z
UUID: 123e4567-e89b-12d3-a456-426614174000
```

## Storage Format

Requests are stored per-topic in a per-request directory: `data/{routeName}/{timestamp}_{uuid}/`:

- `request.json` - full stored request (headers + parsed body + file metadata)
- `body.json` - parsed body only (convenience)
- `files/` - uploaded files (multipart only)

Example `request.json`:

```json
{
    "timestamp": 1702834567890,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "routeName": "my-webhook",
    "method": "POST",
    "headers": {
        "content-type": "application/json"
    },
    "body": {
        "your": "data"
    },
    "files": [
        {
            "fieldName": "attachment",
            "originalFilename": "invoice.pdf",
            "filename": "0_invoice.pdf",
            "contentType": "application/pdf",
            "size": 12345,
            "path": "files/0_invoice.pdf"
        }
    ]
}
```

## Usage

### Development

```bash
npm install
npm run build
export POSTHOOK_TOKEN_SECRET=your-secret-here
npm start -- --port 9000 --host 0.0.0.0 --data-dir ./data
```

### Docker

```bash
docker build -t posthook .
docker run -p 9000:9000 \
  -v $(pwd)/data:/app/data \
  -e POSTHOOK_TOKEN_SECRET=your-secret-here \
  posthook
```

### With OAuth Proxy (Recommended for Production)

Protect admin routes with an OAuth proxy:

```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
```

Then configure your reverse proxy:

- `/admin/*` → OAuth2 Proxy on port 4180
- `/` → Posthook on port 9000

## Configuration

### Command Line Arguments:

- `--port` - Server port (default: 9000)
- `--host` - Server host (default: 0.0.0.0)
- `--data-dir` - Data storage directory (default: ./data)
- `--token-secret` - HMAC secret for token signing (optional, generates random if not provided)

### Environment Variables:

- `POSTHOOK_TOKEN_SECRET` - HMAC secret for token signing (recommended for production)