WebSocket RPC & Webhook Triggers

Direct WebSocket access

For full programmatic control of your OpenClaw helper, connect to its hosted WebSocket bridge. It gives operator access to all 110+ OpenClaw RPC methods: chat, sessions, config, cron jobs, skills, usage, and more.

Requirements: your helper must be running, and you authenticate with your Gateway Token (not a brk_ API key). Both the exact URL and the token are on Dashboard → API → Gateway Connection. The token has full access to your helper; keep it secret.

Hermes helpers do not get this bridge. The dashboard shows Hermes users a Gateway URL and a Hermes OpenAI-compatible base URL instead.

Connection

wss://app.brainroad.com/gw/YOUR_USER_ID/ws

Send the Gateway Token as a bearer header. The hosted bridge authenticates and signs the OpenClaw connect handshake for you, so you only send RPC frames. (Advanced callers who want to do their own device-identity signing can use the raw /gw/YOUR_USER_ID/agent endpoint instead.)

Protocol format

Request (you send):

{"type": "req", "id": "unique-id", "method": "method.name", "params": { ... }}

Response (you receive):

{"type": "res", "id": "unique-id", "ok": true, "payload": { ... }}

Event (server pushes):

{"type": "event", "event": "event.name", "payload": { ... }}

Each request needs a unique id; the response echoes it back.

Example: Python

import asyncio, json, websockets

async def main():
    uri = "wss://app.brainroad.com/gw/YOUR_USER_ID/ws"
    headers = {"Authorization": "Bearer YOUR_GATEWAY_TOKEN"}
    async with websockets.connect(uri, additional_headers=headers) as ws:
        # The hosted bridge authenticates for you — just send RPC.
        await ws.send(json.dumps({
            "type": "req", "id": "1", "method": "chat.send",
            "params": {"message": "What's on my schedule today?"}
        }))
        async for frame in ws:
            print(frame)

asyncio.run(main())

Example: Node.js

import WebSocket from "ws";

const ws = new WebSocket("wss://app.brainroad.com/gw/YOUR_USER_ID/ws", {
  headers: { Authorization: "Bearer YOUR_GATEWAY_TOKEN" },
});
ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "req", id: "1", method: "chat.send",
    params: { message: "What's on my schedule today?" },
  }));
});
ws.on("message", (data) => console.log(JSON.parse(data.toString())));

Discovering methods

The Dashboard → API page lists the RPC methods by category (chat, agents, sessions, config, channels, cron, skills, usage, and more). At runtime, call config.schema to discover every available method and its parameters.

Note that runtime-level control does not bypass the review step for outside-world actions: customer-facing sends still route through your Inbox for approval.

Webhook triggers: wake and task endpoints

You can also point outside tools at your helper. In Dashboard → Settings → Developer Triggers, a running OpenClaw helper shows two URLs plus an auth token:

• Wake Webhook (https://app.brainroad.com/gw/YOUR_USER_ID/hooks/wake): paste into Stripe, GitHub, Zapier, or any tool that sends webhooks. Example body: {"text": "New order received", "mode": "now"}.
• Task Endpoint (https://app.brainroad.com/gw/YOUR_USER_ID/hooks/agent): send the helper a task to work on. Example body: {"message": "Summarize this", "deliver": true}.

Both require the card’s Auth token as a bearer header (Authorization: Bearer ...). You can regenerate the token from the same card at any time, which invalidates the old one.

Constraints:

• The URLs route to the helper itself, so it must be running to receive calls.
• OpenClaw only. Hermes trigger ingestion is not exposed through the dashboard yet.

When to use which surface

Use case	Best option
Claude Code / Codex working from your Business Brain	MCP Integration
Start/stop or status from scripts and CI	REST API
Monitoring and logging	Event Streaming
Outside tools notifying your helper	Webhook triggers (above)
Full runtime control from code	WebSocket RPC (above)