113 lines
1.7 KiB
Markdown
113 lines
1.7 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
|
|
|
|
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`.
|