feat(skill): finish n8n webhook skill

2026-03-12 07:07:21 +00:00
parent 295809b161
commit e0a3694430
9 changed files with 721 additions and 7 deletions
@@ -0,0 +1,148 @@
+# openclaw-action workflow
+
+This skill ships an importable draft workflow at:
+
+- `assets/openclaw-action.workflow.json`
+
+It implements the first safe router contract for local OpenClaw → n8n calls.
+
+## What it does
+
+- accepts `POST /webhook/openclaw-action`
+- normalizes incoming JSON into:
+  - `action`
+  - `args`
+  - `request_id`
+- routes two known actions:
+  - `append_log`
+  - `notify`
+- returns normalized JSON responses
+- returns `400` for unknown actions
+- returns `400` when required branch args are missing
+
+## Intentional security choice
+
+The exported workflow leaves the Webhook node auth unset in the JSON file.
+
+Why:
+- n8n credentials are instance-local
+- secrets should not be embedded in a shareable skill asset
+
+After import, set this manually in n8n:
+
+- Webhook node → **Authentication** → `Header Auth`
+- bind a credential with:
+  - header name: `x-openclaw-secret`
+  - header value: your generated shared secret
+
+## Import steps
+
+1. In n8n, create or open a workflow.
+2. Import `assets/openclaw-action.workflow.json`.
+3. Open the **Webhook** node.
+4. Set **Authentication** to `Header Auth`.
+5. Bind your local credential.
+6. Save.
+7. Use **Listen for test event** and call the test URL first.
+8. Once successful, activate the workflow for production URL use.
+
+## Expected URLs
+
+Assuming the current local service address:
+
+- test: `http://192.168.153.113:18808/webhook-test/openclaw-action`
+- prod: `http://192.168.153.113:18808/webhook/openclaw-action`
+
+## Test payloads included
+
+- `assets/test-append-log.json`
+- `assets/test-notify.json`
+
+## Example tests
+
+Direct curl:
+
+```bash
+curl -i -X POST 'http://192.168.153.113:18808/webhook-test/openclaw-action' \
+  -H 'Content-Type: application/json' \
+  -H 'x-openclaw-secret: YOUR_SECRET_HERE' \
+  --data @assets/test-append-log.json
+```
+
+Via skill helper:
+
+```bash
+export N8N_WEBHOOK_SECRET='YOUR_SECRET_HERE'
+scripts/call-action.sh append_log --args '{"text":"backup complete"}' --test --pretty
+```
+
+## Expected success examples
+
+### append_log
+
+```json
+{
+  "ok": true,
+  "request_id": "test-append-log-001",
+  "result": {
+    "action": "append_log",
+    "status": "accepted",
+    "preview": {
+      "text": "backup complete"
+    }
+  }
+}
+```
+
+### notify
+
+```json
+{
+  "ok": true,
+  "request_id": "test-notify-001",
+  "result": {
+    "action": "notify",
+    "status": "accepted",
+    "preview": {
+      "title": "Workflow finished",
+      "message": "n8n router test"
+    }
+  }
+}
+```
+
+## Expected failure examples
+
+### unknown action
+
+```json
+{
+  "ok": false,
+  "request_id": "",
+  "error": {
+    "code": "unknown_action",
+    "message": "action is not supported"
+  }
+}
+```
+
+### missing required args
+
+```json
+{
+  "ok": false,
+  "request_id": "",
+  "error": {
+    "code": "invalid_request",
+    "message": "required args are missing"
+  }
+}
+```
+
+## Validation
+
+Run the local validator before import/package changes:
+
+```bash
+python3 scripts/validate-workflow.py assets/openclaw-action.workflow.json
+```
@@ -33,6 +33,9 @@ Purpose:
 - keep the external n8n surface small
 - route several agent-safe operations behind one authenticated webhook

+Shipped workflow asset:
+- `assets/openclaw-action.workflow.json`
+
 Recommended request shape:

 ```json
@@ -87,6 +90,9 @@ Request:
 Purpose:
 - append a short line to a known log or tracking sink

+Sample payload file:
+- `assets/test-append-log.json`
+
 ### `notify`

 Request:
@@ -104,6 +110,9 @@ Request:
 Purpose:
 - send a small notification through a known downstream channel

+Sample payload file:
+- `assets/test-notify.json`
+
 ## Naming guidance

 - Use lowercase kebab-case for webhook paths.