swarm-zap/skills/n8n-webhook/references/openclaw-action.md

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:

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:

export N8N_WEBHOOK_SECRET='YOUR_SECRET_HERE'
scripts/call-action.sh append_log --args '{"text":"backup complete"}' --test --pretty

Expected success examples

append_log

{
  "ok": true,
  "request_id": "test-append-log-001",
  "result": {
    "action": "append_log",
    "status": "accepted",
    "preview": {
      "text": "backup complete"
    }
  }
}

notify

{
  "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

{
  "ok": false,
  "request_id": "",
  "error": {
    "code": "unknown_action",
    "message": "action is not supported"
  }
}

missing required args

{
  "ok": false,
  "request_id": "",
  "error": {
    "code": "invalid_request",
    "message": "required args are missing"
  }
}

Validation

Run the local validator before import/package changes:

python3 scripts/validate-workflow.py assets/openclaw-action.workflow.json