feat: add gateway webhooks

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.