# 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

Recommended request shape:

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

Recommended success response:

```json
{
  "ok": true,
  "request_id": "optional-uuid",
  "result": {
    "status": "accepted"
  }
}
```

Recommended failure response:

```json
{
  "ok": false,
  "error": {
    "code": "unknown_action",
    "message": "action is not supported"
  }
}
```

## Suggested initial actions

### `append_log`

Request:

```json
{
  "action": "append_log",
  "args": {
    "text": "backup complete"
  }
}
```

Purpose:
- append a short line to a known log or tracking sink

### `notify`

Request:

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

Purpose:
- send a small notification through a known downstream channel

## 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`, `notify`.
- Avoid generic names like `run`, `task`, or `webhook1`.