swarm-zap/skills/n8n-webhook/references/payloads.md

n8n-webhook payload notes

Current live endpoint

openclaw-ping

Purpose:

• confirm OpenClaw can reach the local n8n webhook surface end-to-end

Typical request body:

{
  "message": "hello from OpenClaw"
}

Recommended success response:

{
  "ok": true,
  "service": "n8n-agent",
  "message": "openclaw webhook reached"
}

Preferred router endpoint

openclaw-action

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:

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

Live actions

append_log

Request:

{
  "action": "append_log",
  "args": {
    "text": "backup complete",
    "meta": {
      "source": "backup-job"
    }
  }
}

Purpose:

• append one small operational breadcrumb into n8n workflow static data

Current sink:

• type: workflow-static-data
• key: actionLog
• retained entries: 200

get_logs

Request:

{
  "action": "get_logs",
  "args": {
    "limit": 10
  }
}

Purpose:

• return the most recent retained log records from workflow static data

Behavior:

• default limit: 20
• min limit: 1
• max limit: 50
• entries are returned newest-first

Success shape:

{
  "ok": true,
  "request_id": "optional-uuid",
  "result": {
    "action": "get_logs",
    "status": "ok",
    "count": 2,
    "total_retained": 7,
    "retained_entries": 200,
    "entries": []
  }
}

notify

Request:

{
  "action": "notify",
  "args": {
    "message": "workflow finished",
    "title": "optional title"
  }
}

Purpose:

• send the message through the currently configured Telegram + Discord notification targets

Success shape:

{
  "ok": true,
  "request_id": "optional-uuid",
  "result": {
    "action": "notify",
    "status": "sent",
    "targets": ["telegram", "discord"]
  }
}

Failure shape

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

Naming guidance

• Use lowercase kebab-case for webhook paths.
• Use lowercase snake_case or kebab-case consistently for action names; prefer snake_case for JSON actions if using switch/router logic.
• Keep names explicit: openclaw-ping, openclaw-action, append_log, get_logs, notify.
• Avoid generic names like run, task, or webhook1.