feat: add gateway webhooks

docs/configuration.md

@@ -311,6 +311,35 @@ Auth and Tailscale:
 - `gateway.tailscale.mode: "funnel"` exposes the dashboard publicly; requires auth.
 - `gateway.tailscale.resetOnExit` resets Serve/Funnel config on shutdown.
 
+### `hooks` (Gateway webhooks)
+
+Enable a simple HTTP webhook surface on the Gateway HTTP server.
+
+Defaults:
+- enabled: `false`
+- path: `/hooks`
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks"
+  }
+}
+```
+
+Requests must include the hook token:
+- `Authorization: Bearer <token>` **or**
+- `x-clawdis-token: <token>` **or**
+- `?token=<token>`
+
+Endpoints:
+- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
+- `POST /hooks/agent` → `{ message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, thinking?, timeoutSeconds? }`
+
+`/hooks/agent` always posts a summary into the main session (and can optionally trigger an immediate heartbeat via `wakeMode: "now"`).
+
 ### `canvasHost` (LAN/tailnet Canvas file server + live reload)
 
 The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply `canvas.navigate` to it.

docs/web.md

@@ -21,6 +21,11 @@ The UI talks directly to the Gateway WS and supports:
 - Config (`config.get`, `config.set`) for `~/.clawdis/clawdis.json`
 - Debug (status/health/models snapshots + manual calls)
 
+## Webhooks
+
+When `hooks.enabled=true`, the Gateway also exposes a small webhook surface on the same HTTP server.
+See `docs/configuration.md` → `hooks` for auth + payloads.
+
 ## Config (default-on)
 
 The Control UI is **enabled by default** when assets are present (`dist/control-ui`).

docs/webhook.md

@@ -0,0 +1,111 @@
+---
+summary: "Webhook ingress for wake and isolated agent runs"
+read_when:
+  - Adding or changing webhook endpoints
+  - Wiring external systems into Clawdis
+---
+
+# Webhooks
+
+Gateway can expose a small HTTP webhook surface for external triggers.
+
+## Enable
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks"
+  }
+}
+```
+
+Notes:
+- `hooks.token` is required when `hooks.enabled=true`.
+- `hooks.path` defaults to `/hooks`.
+
+## Auth
+
+Every request must include the hook token:
+- `Authorization: Bearer <token>`
+- or `x-clawdis-token: <token>`
+- or `?token=<token>`
+
+## Endpoints
+
+### `POST /hooks/wake`
+
+Payload:
+```json
+{ "text": "System line", "mode": "now" }
+```
+
+- `text` required (string)
+- `mode` optional: `now` | `next-heartbeat` (default `now`)
+
+Effect:
+- Enqueues a system event for the **main** session
+- If `mode=now`, triggers an immediate heartbeat
+
+### `POST /hooks/agent`
+
+Payload:
+```json
+{
+  "message": "Run this",
+  "name": "Email",
+  "sessionKey": "hook:email:msg-123",
+  "wakeMode": "now",
+  "deliver": false,
+  "channel": "last",
+  "to": "+15551234567",
+  "thinking": "low",
+  "timeoutSeconds": 120
+}
+```
+
+- `message` required (string)
+- `name` optional (used in the summary prefix)
+- `sessionKey` optional (default random `hook:<uuid>`)
+- `wakeMode` optional: `now` | `next-heartbeat` (default `now`)
+- `deliver` optional (default `false`)
+- `channel` optional: `last` | `whatsapp` | `telegram`
+- `to` optional (channel-specific target)
+- `thinking` optional (override)
+- `timeoutSeconds` optional
+
+Effect:
+- Runs an **isolated** agent turn (own session key)
+- Always posts a summary into the **main** session
+- If `wakeMode=now`, triggers an immediate heartbeat
+
+## Responses
+
+- `200` for `/hooks/wake`
+- `202` for `/hooks/agent` (async run started)
+- `401` on auth failure
+- `400` on invalid payload
+- `413` on oversized payloads
+
+## Examples
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/wake \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"New email received","mode":"now"}'
+```
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-clawdis-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
+```
+
+## Security
+
+- Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
+- Use a dedicated hook token; do not reuse gateway auth tokens.
+- Avoid including sensitive raw payloads in webhook logs.