swarm-zap/skills/n8n-webhook/SKILL.md

name, description

name

description

n8n-webhook

Trigger authenticated local n8n webhooks on the LAN for OpenClaw-to-n8n integration. Use when calling safe, narrow workflows on the dedicated local n8n-agent instance, such as ping/test endpoints, an action-bus style router workflow, notifications, logging, or other preapproved webhook entrypoints. Do not use for broad n8n admin/API management, workflow mutation, credential management, or unrestricted orchestration.

N8n Webhook

Use this skill to call the local n8n-agent webhook surface on:

• http://192.168.153.113:18808 (primary LAN)
• http://100.123.88.127:18808 (Tailscale)

Keep the integration narrow: let OpenClaw decide what to do, and let n8n execute a small set of explicit workflows.

Policy

1. Prefer named webhook entrypoints over generic admin APIs.
2. Prefer one small router webhook (openclaw-action) when several agent-safe actions are needed.
3. Send JSON and expect JSON back.
4. Use header auth by default (x-openclaw-secret).
5. Use /webhook-test/ only while building/editing a workflow.
6. Surface non-2xx responses clearly instead of pretending success.
7. Keep secrets in n8n credentials or local env vars, never inside shareable workflow JSON.
8. If a new workflow is needed, define its request/response contract before wiring callers.

What ships with this skill

• direct webhook caller: scripts/call-webhook.sh
• action-bus caller: scripts/call-action.sh
• workflow validator: scripts/validate-workflow.py
• importable router workflow: assets/openclaw-action.workflow.json
• sample payloads:
  • assets/test-append-log.json
  • assets/test-notify.json

Quick usage

Set the shared secret once for the shell session:

export N8N_WEBHOOK_SECRET='replace-me'

Call a production webhook directly:

scripts/call-webhook.sh openclaw-ping --data '{"message":"hello from OpenClaw"}'

Call the preferred action-bus route:

scripts/call-action.sh append_log --args '{"text":"backup complete"}' --request-id auto

Call a test webhook while editing a flow:

scripts/call-action.sh notify --args '{"message":"hello from OpenClaw"}' --test --pretty

Validate the shipped workflow asset:

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

Workflow

Call an existing safe webhook directly

Use scripts/call-webhook.sh when the path is already defined and there is no benefit to the action-bus wrapper.

Current known direct endpoint:

• openclaw-ping — basic end-to-end connectivity check

Call the action bus

Use scripts/call-action.sh when the n8n side exposes a router webhook such as openclaw-action.

Payload shape:

{
  "action": "append_log",
  "args": {
    "text": "backup complete"
  },
  "request_id": "optional-uuid"
}

This keeps the external surface small while letting n8n route internally.

Import the shipped router workflow

Use the included workflow asset when you want a ready-made local router for:

• append_log → append small records into workflow static data (actionLog, latest 200)
• notify → send through the current Telegram + Discord notification paths
• normalized JSON success/failure responses
• unknown-action handling

Important:

• the workflow export intentionally leaves Webhook authentication unset
• after import, manually set Authentication = Header Auth on the Webhook node and bind a local credential using x-openclaw-secret
• the shipped asset already includes the live side-effect shape for local JSONL logging plus Telegram/Discord fan-out

See references/openclaw-action.md for import and test steps.

Add a new webhook-backed capability

1. Write down the webhook path, required auth, request JSON, and response JSON.
2. If the path should become part of the shared action bus, document the action name and args shape in references/payloads.md.
3. If the shipped workflow should support it, update assets/openclaw-action.workflow.json and rerun scripts/validate-workflow.py.
4. Keep the first version small and explicit.
5. Only add the new endpoint to regular use after a successful /webhook-test/ run.
6. For append-style event logging, prefer workflow static data for small recent breadcrumbs; use MinIO later for rotation, batching, archival, or sharing rather than tiny object-per-line writes.

Environment variables

• N8N_BASE_URL — override base URL (default http://192.168.153.113:18808)
• N8N_WEBHOOK_SECRET — required shared secret for authenticated calls
• N8N_SECRET_HEADER — header name (default x-openclaw-secret)
• N8N_ACTION_PATH — router path for call-action.sh (default openclaw-action)

Resources

• scripts/call-webhook.sh — authenticated POST helper for direct local n8n webhooks
• scripts/call-action.sh — wrapper for action-bus style calls against openclaw-action
• scripts/validate-workflow.py — local structural validator for the shipped workflow asset
• assets/openclaw-action.workflow.json — importable starter workflow for the action bus
• references/openclaw-action.md — import, auth-binding, and testing guide
• references/payloads.md — request/response contracts and naming conventions