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
• approval executor bridge: scripts/resolve-approval-with-gog.py
• 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
  • assets/test-send-notification-draft.json
  • assets/test-send-email-draft.json
  • assets/test-list-email-drafts.json
  • assets/test-delete-email-draft.json
  • assets/test-send-gmail-draft.json
  • assets/test-send-approved-email.json
  • assets/test-create-calendar-event.json
  • assets/test-list-upcoming-events.json
  • assets/test-update-calendar-event.json
  • assets/test-delete-calendar-event.json
  • assets/test-verify-email-draft-cycle.json
  • assets/test-verify-calendar-event-cycle.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
scripts/call-action.sh get_logs --args '{"limit":5}' --pretty
scripts/call-action.sh list_email_drafts --args '{"max":10}' --pretty
scripts/call-action.sh list_upcoming_events --args '{"days":7,"max":10}' --pretty
scripts/call-action.sh approval_queue_list --args '{"limit":5,"include_history":true}' --pretty

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)
• get_logs → read the most recent retained records from actionLog
• notify → send through the current Telegram + Discord notification paths
• send_notification_draft → queue approval-gated notifications that execute on approve through Telegram + Discord
• send_email_draft → queue approval-gated email draft creation proposals in workflow static data
• list_email_drafts → queue approval-gated Gmail draft list requests (read-only, low mutation level)
• delete_email_draft → queue approval-gated Gmail draft deletion requests
• send_gmail_draft (alias: send_approved_email) → queue approval-gated Gmail draft send requests
• create_calendar_event → queue approval-gated calendar creation proposals in workflow static data
• list_upcoming_events → queue approval-gated calendar event listing requests (read-only, low mutation level)
• update_calendar_event → queue approval-gated calendar event update requests
• delete_calendar_event → queue approval-gated calendar event deletion requests
• approval_queue_add / approval_queue_list / approval_queue_resolve → manage pending approvals and recent history
• approval_history_attach_execution → let a host-side executor attach real execution metadata back onto approval history entries
• fetch_and_normalize_url → fetch + normalize URL content using n8n runtime HTTP helpers
• inbound_event_filter → classify, dedupe, store, and optionally notify on inbound events
• 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 uses workflow static data for small queues/state; it does not embed secrets or require provider credentials for the starter approval-gated actions

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

Host execution bridge for Gmail/Calendar

When email/calendar provider creds live on the host via gog rather than inside n8n, use:

python3 scripts/resolve-approval-with-gog.py --id <approval-id> --decision approve

Supported host-executed approval kinds:

• email_draft → gog gmail drafts create
• email_list_drafts → gog gmail drafts list
• email_draft_delete → gog gmail drafts delete
• email_draft_send → gog gmail drafts send
• calendar_event → gog calendar create
• calendar_list_events → gog calendar events
• calendar_event_update → gog calendar update
• calendar_event_delete → gog calendar delete

Practical note:

• unattended execution needs GOG_KEYRING_PASSWORD available to the executor because gog's file keyring cannot prompt in non-TTY automation
• the included bridge auto-loads /home/openclaw/.openclaw/credentials/gog.env when present, so you can keep GOG_ACCOUNT and GOG_KEYRING_PASSWORD there with mode 600
• for safe plumbing tests without touching Google state, add --dry-run
• approval queue/history reads now expose compact pending_compact / history_compact entries plus summary_line + result_refs for low-noise operator review

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