From 2f204bb442bf307700cb365fd465ad35f23ea499 Mon Sep 17 00:00:00 2001
From: oonyeje <oonyeje@bsidesol.com>
Date: Tue, 7 Jul 2026 04:11:46 +0000
Subject: [PATCH] Replace placeholder README with full setup, configuration,
 and multi-project docs

---
 README.md | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 181 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cf6b0b6..b9f8fbc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,183 @@
 # bside-webhook-proxy
 
-Multi-project webhook proxy for incoming webhooks
\ No newline at end of file
+Multi-project webhook proxy for incoming webhooks (Square, Stripe, GitHub, etc.).
+
+Services like Square can deliver webhooks but cannot add custom HTTP headers like `X-Appwrite-Project`. This proxy receives those webhooks, looks up the matching project's API key from its environment config, and forwards the request to the right Appwrite function with the proper auth headers.
+
+One proxy serves all projects — routing is driven entirely by environment variables.
+
+---
+
+## How it works
+
+```
+Caller (Square, etc.)
+   │
+   │ POST raw webhook payload
+   ▼
+https://app-proxy.bsidesolutions.net/square
+   │
+   │ Express server resolves:
+   │   ROUTE_MAP["/square"] = { apiKeySlot: "square", functionId: "verify_square_webhook" }
+   │   PROJECT_CREDENTIALS["square"] = { project: "staging-crown-x-ms-monet", key: "..." }
+   │
+   ▼
+POST https://appwrite.bsidesolutions.net/v1/functions/verify_square_webhook/executions
+Headers: X-Appwrite-Project + X-Appwrite-Key
+   │
+   ▼
+Appwrite function runs, returns response, proxy returns it to caller.
+```
+
+---
+
+## Quick start
+
+### Local
+
+```bash
+cp .env.example .env
+# edit .env to fill in PROJECT_CREDENTIALS and ROUTE_MAP
+
+npm install
+npm start
+```
+
+### Docker
+
+```bash
+docker build -t bside-webhook-proxy .
+docker run --rm -p 3012:3012 \
+  -e PROJECT_CREDENTIALS='{"square":{"project":"...","key":"..."}}' \
+  -e ROUTE_MAP='/square=>{"apiKeySlot":"square","functionId":"verify_square_webhook"}' \
+  bside-webhook-proxy
+```
+
+### Coolify
+
+1. In Coolify → **Add New Resource** → **Application** → **Public/Private Repo**
+2. Point at `bside-solutions/bside-webhook-proxy`
+3. Coolify auto-builds the Dockerfile
+4. Set the domain (e.g. `app-proxy.bsidesolutions.net`)
+5. Add environment variables (see [Configuration](#configuration))
+6. Deploy
+
+---
+
+## Configuration
+
+All credentials live in environment variables — nothing secret is ever committed.
+
+### `PROJECT_CREDENTIALS` (required)
+
+JSON object mapping slot names → `{ project, apiKey }`.
+
+```json
+{
+  "square": {
+    "project": "staging-crown-x-ms-monet",
+    "apiKey": "<appwrite-api-key-with-functions.write-scope>"
+  },
+  "stripe": {
+    "project": "staging-other-project",
+    "apiKey": "<appwrite-api-key-with-functions.write-scope>"
+  }
+}
+```
+
+### `ROUTE_MAP` (optional)
+
+Maps short paths to `{ apiKeySlot, functionId }`. Format:
+
+```
+/path=>{"apiKeySlot":"slot-name","functionId":"function-name"};
+/path2=>{"apiKeySlot":"slot-name-2","functionId":"function-name-2"}
+```
+
+Example:
+
+```
+/square=>{"apiKeySlot":"square","functionId":"verify_square_webhook"};
+/stripe=>{"apiKeySlot":"stripe","functionId":"verify_stripe_webhook"}
+```
+
+If a short-path route matches, the proxy uses its config directly. Otherwise, the caller must pass `project`, `function`, and `apiKey` as querystring params.
+
+### `APPWRITE_BASE_URL` (optional)
+
+Default: `https://appwrite.bsidesolutions.net/v1`. Override if your Appwrite API lives elsewhere.
+
+### `PORT` (optional)
+
+Default: `3012`.
+
+---
+
+## Webhook URL formats
+
+Either of these work:
+
+### Short path (uses ROUTE_MAP)
+
+```
+POST https://app-proxy.bsidesolutions.net/square
+```
+
+### Explicit querystring (always works, no route config needed)
+
+```
+POST https://app-proxy.bsidesolutions.net?project=staging-crown-x-ms-monet&function=verify_square_webhook&apiKey=square
+```
+
+---
+
+## Health check
+
+```
+GET https://app-proxy.bsidesolutions.net/health
+```
+
+Returns:
+
+```json
+{
+  "status": "ok",
+  "projects": ["square"],
+  "routes": ["/square"],
+  "timestamp": "2026-07-07T..."
+}
+```
+
+---
+
+## Adding a new project / webhook
+
+1. Generate an API key in the target Appwrite project with `functions.write` scope
+2. Update `PROJECT_CREDENTIALS` JSON env var on the proxy service to include the new slot
+3. Add a route entry to `ROUTE_MAP` env var if you want a short URL
+4. Restart the proxy container
+
+No code changes needed.
+
+---
+
+## Local development
+
+```bash
+npm install
+npm start
+```
+
+To test forwarding:
+
+```bash
+curl -X POST 'http://localhost:3012/square' \
+  -H 'Content-Type: application/json' \
+  -d '{"test": true}'
+```
+
+---
+
+## License
+
+MIT
\ No newline at end of file