166 lines
2.5 KiB
Markdown
166 lines
2.5 KiB
Markdown
# 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`.
|