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 in the shipped workflow asset

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

notify

Request:

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

Purpose:

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

send_email_draft

Request:

{
  "action": "send_email_draft",
  "args": {
    "to": ["will@example.com"],
    "subject": "Draft daily brief",
    "body_text": "Here is a draft daily brief for review."
  }
}

Purpose:

• queue an email draft proposal for approval
• does not send mail directly in the shipped starter workflow

Sink:

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

create_calendar_event

Request:

{
  "action": "create_calendar_event",
  "args": {
    "calendar": "primary",
    "title": "Call with vendor",
    "start": "2026-03-13T18:00:00Z",
    "end": "2026-03-13T18:30:00Z",
    "description": "Drafted from OpenClaw action bus."
  }
}

Purpose:

• queue a calendar event proposal for approval
• does not write to a calendar provider directly in the shipped starter workflow

Sink:

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

approval_queue_add

Request:

{
  "action": "approval_queue_add",
  "args": {
    "kind": "manual",
    "summary": "Review outbound customer reply",
    "payload": {
      "channel": "email"
    },
    "tags": ["approval", "customer"]
  }
}

Purpose:

• add a generic pending approval item to the queue

approval_queue_list

Request:

{
  "action": "approval_queue_list",
  "args": {
    "limit": 10,
    "include_history": true
  }
}

Purpose:

• inspect pending approval items
• optionally include recent resolved history

approval_queue_resolve

Request:

{
  "action": "approval_queue_resolve",
  "args": {
    "id": "approval-abc123",
    "decision": "approve",
    "note": "Looks good",
    "notify_on_resolve": true
  }
}

Purpose:

• approve or reject a pending item
• moves resolved entries into approvalHistory

fetch_and_normalize_url

Request:

{
  "action": "fetch_and_normalize_url",
  "args": {
    "url": "https://example.com/article",
    "max_chars": 8000,
    "timeout_ms": 10000
  }
}

Purpose:

• fetch a URL inside n8n
• normalize content into a predictable summary-ready shape

Success shape includes:

• url
• title
• content_type
• http_status
• excerpt
• body_text
• text_length
• truncated

inbound_event_filter

Request:

{
  "action": "inbound_event_filter",
  "args": {
    "source": "homelab",
    "type": "alert",
    "severity": "critical",
    "summary": "Build failed on swarm cluster",
    "notify": true
  }
}

Purpose:

• dedupe and classify inbound events
• store recent events in workflow static data
• optionally notify on urgent/important events

Sinks:

• inboundEvents
• eventDedup

Common 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 for JSON action names.
• Keep names explicit: openclaw-ping, openclaw-action, append_log, approval_queue_resolve.
• Avoid generic names like run, task, or webhook1.