Webhooks

Tulsk uses webhooks to receive results and updates from OpenClaw agents running on remote VPS instances.

Agent Result Webhook

When an agent finishes work on an OpenClaw cluster, the bridge sidecar sends the result back to Tulsk via webhook.

Endpoint

POST /api/openclaw/webhook

Authentication

The request includes a webhookToken in the Authorization: Bearer header. This token is unique to each OpenClaw instance.

Payload Example


{
  "success": true,
  "response": "The agent's response text...",
  "metadata": {
    "agentRunId": "uuid",
    "taskId": "uuid",
    "agentId": "uuid",
    "commentId": "uuid"
  },
  "tokens_used": 1500,
  "duration_ms": 25000
}

Processing Logic

Verification

Tulsk verifies the webhookToken and looks up the corresponding AgentRun.

Update Task

The placeholder comment in the task thread is updated with the real response text.

Status Update

The AgentRun is marked as COMPLETED or FAILED, and current run counts are updated.

Real-time Event

A real-time event is published via Redis SSE so the UI updates instantly.

EMA Integration

If the run has an associated chatId, the result is pushed as a new message to the EMA chat.

Streaming Webhook

For real-time token streaming, the bridge sends incremental chunks.

Endpoint

POST /api/openclaw/webhook/stream

The bridge publishes streaming chunks directly to Redis (Upstash REST API), bypassing the Tulsk API for lower latency and better scaling.

Heartbeat

The bridge sends a heartbeat every 60 seconds to confirm the VPS is alive.

Endpoint

POST /api/openclaw/heartbeat

Actions

Updates the instance’s lastSeenAt timestamp.
Sets health status to HEALTHY.
Transitions PROVISIONING instances to RUNNING.
Returns any pending configuration updates (e.g., new agent personas).