will/swarm-zap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
295809b1613ffa5c5e842cea3f6e7d7b6ef68f73
swarm-zap/skills/n8n-webhook/SKILL.md
zap 295809b161 feat(skill): add n8n action-bus helper
2026-03-12 06:51:15 +00:00

3.3 KiB
Raw Blame History

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. If a new workflow is needed, define its request/response contract before wiring callers.

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"}'

Call a test webhook while editing a flow:

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

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.

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. Keep the first version small and explicit.
  4. Only add the new endpoint to regular use after a successful /webhook-test/ run.

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
  • references/payloads.md — request/response contracts and naming conventions