191 lines
8.7 KiB
Markdown
191 lines
8.7 KiB
Markdown
---
|
|
name: n8n-webhook
|
|
description: Trigger authenticated local n8n webhooks on the LAN for OpenClaw-to-n8n integration. Use when calling safe, narrow workflows on the dedicated local n8n-agent instance, such as ping/test endpoints, an action-bus style router workflow, notifications, logging, or other preapproved webhook entrypoints. Do not use for broad n8n admin/API management, workflow mutation, credential management, or unrestricted orchestration.
|
|
---
|
|
|
|
# N8n Webhook
|
|
|
|
Use this skill to call the local `n8n-agent` webhook surface on:
|
|
|
|
- `http://192.168.153.113:18808` (primary LAN)
|
|
- `http://100.123.88.127:18808` (Tailscale)
|
|
|
|
Keep the integration narrow: let OpenClaw decide what to do, and let n8n execute a small set of explicit workflows.
|
|
|
|
## Policy
|
|
|
|
1. Prefer named webhook entrypoints over generic admin APIs.
|
|
2. Prefer one small router webhook (`openclaw-action`) when several agent-safe actions are needed.
|
|
3. Send JSON and expect JSON back.
|
|
4. Use header auth by default (`x-openclaw-secret`).
|
|
5. Use `/webhook-test/` only while building/editing a workflow.
|
|
6. Surface non-2xx responses clearly instead of pretending success.
|
|
7. Keep secrets in n8n credentials or local env vars, never inside shareable workflow JSON.
|
|
8. If a new workflow is needed, define its request/response contract before wiring callers.
|
|
|
|
## What ships with this skill
|
|
|
|
- direct webhook caller: `scripts/call-webhook.sh`
|
|
- action-bus caller: `scripts/call-action.sh`
|
|
- approval executor bridge: `scripts/resolve-approval-with-gog.py`
|
|
- workflow validator: `scripts/validate-workflow.py`
|
|
- importable router workflow: `assets/openclaw-action.workflow.json`
|
|
- sample payloads:
|
|
- `assets/test-append-log.json`
|
|
- `assets/test-notify.json`
|
|
- `assets/test-send-notification-draft.json`
|
|
- `assets/test-send-email-draft.json`
|
|
- `assets/test-list-email-drafts.json`
|
|
- `assets/test-delete-email-draft.json`
|
|
- `assets/test-send-gmail-draft.json`
|
|
- `assets/test-send-approved-email.json`
|
|
- `assets/test-create-calendar-event.json`
|
|
- `assets/test-list-upcoming-events.json`
|
|
- `assets/test-update-calendar-event.json`
|
|
- `assets/test-delete-calendar-event.json`
|
|
- `assets/test-verify-email-draft-cycle.json`
|
|
- `assets/test-verify-calendar-event-cycle.json`
|
|
|
|
## Quick usage
|
|
|
|
Set the shared secret once for the shell session:
|
|
|
|
```bash
|
|
export N8N_WEBHOOK_SECRET='replace-me'
|
|
```
|
|
|
|
Call a production webhook directly:
|
|
|
|
```bash
|
|
scripts/call-webhook.sh openclaw-ping --data '{"message":"hello from OpenClaw"}'
|
|
```
|
|
|
|
Call the preferred action-bus route:
|
|
|
|
```bash
|
|
scripts/call-action.sh append_log --args '{"text":"backup complete"}' --request-id auto
|
|
scripts/call-action.sh get_logs --args '{"limit":5}' --pretty
|
|
scripts/call-action.sh list_email_drafts --args '{"max":10}' --pretty
|
|
scripts/call-action.sh list_upcoming_events --args '{"days":7,"max":10}' --pretty
|
|
scripts/call-action.sh approval_queue_list --args '{"limit":5,"include_history":true}' --pretty
|
|
```
|
|
|
|
Call a test webhook while editing a flow:
|
|
|
|
```bash
|
|
scripts/call-action.sh notify --args '{"message":"hello from OpenClaw"}' --test --pretty
|
|
```
|
|
|
|
Validate the shipped workflow asset:
|
|
|
|
```bash
|
|
python3 scripts/validate-workflow.py assets/openclaw-action.workflow.json
|
|
```
|
|
|
|
## Workflow
|
|
|
|
### Call an existing safe webhook directly
|
|
|
|
Use `scripts/call-webhook.sh` when the path is already defined and there is no benefit to the action-bus wrapper.
|
|
|
|
Current known direct endpoint:
|
|
|
|
- `openclaw-ping` — basic end-to-end connectivity check
|
|
|
|
### Call the action bus
|
|
|
|
Use `scripts/call-action.sh` when the n8n side exposes a router webhook such as `openclaw-action`.
|
|
|
|
Payload shape:
|
|
|
|
```json
|
|
{
|
|
"action": "append_log",
|
|
"args": {
|
|
"text": "backup complete"
|
|
},
|
|
"request_id": "optional-uuid"
|
|
}
|
|
```
|
|
|
|
This keeps the external surface small while letting n8n route internally.
|
|
|
|
### Import the shipped router workflow
|
|
|
|
Use the included workflow asset when you want a ready-made local router for:
|
|
|
|
- `append_log` → append small records into workflow static data (`actionLog`, latest 200)
|
|
- `get_logs` → read the most recent retained records from `actionLog`
|
|
- `notify` → send through the current Telegram + Discord notification paths
|
|
- `send_notification_draft` → queue approval-gated notifications that execute on approve through Telegram + Discord
|
|
- `send_email_draft` → queue approval-gated email draft creation proposals in workflow static data
|
|
- `list_email_drafts` → queue approval-gated Gmail draft list requests (read-only, low mutation level)
|
|
- `delete_email_draft` → queue approval-gated Gmail draft deletion requests
|
|
- `send_gmail_draft` (alias: `send_approved_email`) → queue approval-gated Gmail draft send requests
|
|
- `create_calendar_event` → queue approval-gated calendar creation proposals in workflow static data
|
|
- `list_upcoming_events` → queue approval-gated calendar event listing requests (read-only, low mutation level)
|
|
- `update_calendar_event` → queue approval-gated calendar event update requests
|
|
- `delete_calendar_event` → queue approval-gated calendar event deletion requests
|
|
- `approval_queue_add` / `approval_queue_list` / `approval_queue_resolve` → manage pending approvals and recent history
|
|
- `approval_history_attach_execution` → let a host-side executor attach real execution metadata back onto approval history entries
|
|
- `fetch_and_normalize_url` → fetch + normalize URL content using n8n runtime HTTP helpers
|
|
- `inbound_event_filter` → classify, dedupe, store, and optionally notify on inbound events
|
|
- normalized JSON success/failure responses
|
|
- unknown-action handling
|
|
|
|
Important:
|
|
- the workflow export intentionally leaves Webhook authentication unset
|
|
- after import, manually set **Authentication = Header Auth** on the Webhook node and bind a local credential using `x-openclaw-secret`
|
|
- the shipped asset uses workflow static data for small queues/state; it does not embed secrets or require provider credentials for the starter approval-gated actions
|
|
|
|
See `references/openclaw-action.md` for import and test steps.
|
|
|
|
### Host execution bridge for Gmail/Calendar
|
|
|
|
When email/calendar provider creds live on the host via `gog` rather than inside n8n, use:
|
|
|
|
```bash
|
|
python3 scripts/resolve-approval-with-gog.py --id <approval-id> --decision approve
|
|
```
|
|
|
|
Supported host-executed approval kinds:
|
|
- `email_draft` → `gog gmail drafts create`
|
|
- `email_list_drafts` → `gog gmail drafts list`
|
|
- `email_draft_delete` → `gog gmail drafts delete`
|
|
- `email_draft_send` → `gog gmail drafts send`
|
|
- `calendar_event` → `gog calendar create`
|
|
- `calendar_list_events` → `gog calendar events`
|
|
- `calendar_event_update` → `gog calendar update`
|
|
- `calendar_event_delete` → `gog calendar delete`
|
|
|
|
Practical note:
|
|
- unattended execution needs `GOG_KEYRING_PASSWORD` available to the executor because `gog`'s file keyring cannot prompt in non-TTY automation
|
|
- the included bridge auto-loads `/home/openclaw/.openclaw/credentials/gog.env` when present, so you can keep `GOG_ACCOUNT` and `GOG_KEYRING_PASSWORD` there with mode `600`
|
|
- for safe plumbing tests without touching Google state, add `--dry-run`
|
|
- approval queue/history reads now expose compact `pending_compact` / `history_compact` entries plus `summary_line` + `result_refs` for low-noise operator review
|
|
|
|
### Add a new webhook-backed capability
|
|
|
|
1. Write down the webhook path, required auth, request JSON, and response JSON.
|
|
2. If the path should become part of the shared action bus, document the `action` name and `args` shape in `references/payloads.md`.
|
|
3. If the shipped workflow should support it, update `assets/openclaw-action.workflow.json` and rerun `scripts/validate-workflow.py`.
|
|
4. Keep the first version small and explicit.
|
|
5. Only add the new endpoint to regular use after a successful `/webhook-test/` run.
|
|
6. For append-style event logging, prefer workflow static data for small recent breadcrumbs; use MinIO later for rotation, batching, archival, or sharing rather than tiny object-per-line writes.
|
|
|
|
## Environment variables
|
|
|
|
- `N8N_BASE_URL` — override base URL (default `http://192.168.153.113:18808`)
|
|
- `N8N_WEBHOOK_SECRET` — required shared secret for authenticated calls
|
|
- `N8N_SECRET_HEADER` — header name (default `x-openclaw-secret`)
|
|
- `N8N_ACTION_PATH` — router path for `call-action.sh` (default `openclaw-action`)
|
|
|
|
## Resources
|
|
|
|
- `scripts/call-webhook.sh` — authenticated POST helper for direct local n8n webhooks
|
|
- `scripts/call-action.sh` — wrapper for action-bus style calls against `openclaw-action`
|
|
- `scripts/validate-workflow.py` — local structural validator for the shipped workflow asset
|
|
- `assets/openclaw-action.workflow.json` — importable starter workflow for the action bus
|
|
- `references/openclaw-action.md` — import, auth-binding, and testing guide
|
|
- `references/payloads.md` — request/response contracts and naming conventions
|