# 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:

```json
{
  "message": "hello from OpenClaw"
}
```

Recommended success response:

```json
{
  "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:

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

## Live actions

### `append_log`

Request:

```json
{
  "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:

```json
{
  "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:

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

### `notify`

Request:

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

Purpose:
- send the message through the currently configured Telegram + Discord notification targets

Success shape:

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

## Failure shape

```json
{
  "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`.