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

Approval defaults by family

• notification family
  • send_notification_draft
  • approval.family = "notification"
  • approval.required = true
  • approval.mutation_level = "high"
• Gmail family
  • read-only: list_email_drafts → approval.family = "gmail", approval.mutation_level = "low"
  • mutating: send_email_draft, delete_email_draft, send_gmail_draft / send_approved_email → approval.family = "gmail", approval.mutation_level = "high"
• Calendar family
  • read-only: list_upcoming_events → approval.family = "calendar", approval.mutation_level = "low"
  • mutating: create_calendar_event, update_calendar_event, delete_calendar_event → approval.family = "calendar", approval.mutation_level = "high"
• manual/generic approvals
  • approval_queue_add leaves side effects to the operator; there is no automatic host executor for arbitrary manual kinds

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_notification_draft

Request:

{
  "action": "send_notification_draft",
  "args": {
    "title": "optional title",
    "message": "Please review this notification before send"
  }
}

Purpose:

• queue a notification for approval
• when the pending item is later approved through approval_queue_resolve, it executes the existing notify path and fans out through Telegram + Discord

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

Approval policy:

• required: true
• mutation level: high

Sink:

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

list_email_drafts

Request:

{
  "action": "list_email_drafts",
  "args": {
    "max": 20,
    "all": false
  }
}

Purpose:

• queue a host-side Gmail draft listing request for approval/audit

Approval policy:

• required: true
• mutation level: low (read-only)

delete_email_draft

Request:

{
  "action": "delete_email_draft",
  "args": {
    "draft_id": "r-example-draft-id"
  }
}

Purpose:

• queue deletion of a Gmail draft behind explicit approval

Approval policy:

• required: true
• mutation level: high

send_gmail_draft (alias: send_approved_email)

Request:

{
  "action": "send_gmail_draft",
  "args": {
    "draft_id": "r-example-draft-id"
  }
}

Purpose:

• queue sending of an existing Gmail draft behind explicit approval

Approval policy:

• required: true
• mutation level: high

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

Approval policy:

• required: true
• mutation level: high

Sink:

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

list_upcoming_events

Request:

{
  "action": "list_upcoming_events",
  "args": {
    "calendar": "primary",
    "days": 7,
    "max": 10,
    "query": "zap"
  }
}

Purpose:

• queue a host-side upcoming calendar event listing request for approval/audit
• defaults to the next 7 days when no explicit from/to window is provided

Approval policy:

• required: true
• mutation level: low (read-only)

update_calendar_event

Request:

{
  "action": "update_calendar_event",
  "args": {
    "calendar": "primary",
    "event_id": "example-calendar-event-id",
    "title": "Updated call with vendor",
    "start": "2026-03-13T18:15:00Z",
    "end": "2026-03-13T18:45:00Z",
    "location": "Updated room",
    "description": "Updated by OpenClaw action bus.",
    "send_updates": "none"
  }
}

Purpose:

• queue an update to an existing calendar event behind explicit approval
• requires event_id and at least one patch field (title, start, end, location, description, or attendees)

Approval policy:

• required: true
• mutation level: high

delete_calendar_event

Request:

{
  "action": "delete_calendar_event",
  "args": {
    "calendar": "primary",
    "event_id": "example-calendar-event-id",
    "send_updates": "none"
  }
}

Purpose:

• queue deletion of an existing calendar event behind explicit approval

Approval policy:

• required: true
• mutation level: high

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
• returns both raw entries and compact operator-friendly summaries at:
  • result.pending_compact
  • result.history_compact

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
• executes notification drafts inline when the resolved item kind is notification

approval_history_attach_execution

Request:

{
  "action": "approval_history_attach_execution",
  "args": {
    "id": "approval-abc123",
    "execution": {
      "driver": "gog",
      "op": "gmail.drafts.create",
      "status": "draft_created"
    }
  }
}

Purpose:

• patch a resolved history item with host-side execution metadata after a real executor runs outside n8n
• intended for bridges such as gog-backed Gmail/Calendar execution
• compact execution reporting should populate or expose:
  • execution.summary
  • execution.result_refs
  • item.operator.summary_line
  • item.operator.execution_state

fetch_and_normalize_url

Request:

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

Purpose:

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

Notes:

• skip_ssl_certificate_validation is optional and defaults to false
• set it to true only when you explicitly need to work around broken/missing CA trust in the n8n runtime
• for a stable local smoke test, prefer an HTTP URL you control such as the local n8n /healthz endpoint

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.