---
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. If a new workflow is needed, define its request/response contract before wiring callers.

## 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"}'
```

Call a test webhook while editing a flow:

```bash
scripts/call-action.sh notify --args '{"message":"hello from OpenClaw"}' --test --pretty
```

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

### 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. Keep the first version small and explicit.
4. Only add the new endpoint to regular use after a successful `/webhook-test/` run.

## 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`
- `references/payloads.md` — request/response contracts and naming conventions