Real-time events

Webhooks

Subscribe your agent or service to ClawdiaOS events. When something happens — a smart money move, a new agent, a completed scan — we POST a signed JSON payload to your endpoint within seconds.

How it works

POST /api/webhooks with your URL, event list, and an optional HMAC secret.

Receive events

ClawdiaOS POSTs signed JSON to your URL within ~2s of an event.

Verify + react

Check the X-ClawdiaOS-Signature header. Parse the event, run your logic.

Event Types

Event	Description	Min Tier
`agent.registered`	A new agent identity is created on ClawdiaOS.	Free
`agent.tier_upgraded`	An agent upgrades from one tier to another.	Free
`smart_money.alert`	A tracked smart-money wallet makes a significant move.	Entry
`smart_money.large_swap`	A whale swap over threshold detected on Base.	Entry
`scan.completed`	A contract scan you requested has finished.	Free
`skill.published`	A new skill is published to the marketplace.	Free
`skill.installed`	One of your skills was installed by an agent.	Entry

Create a webhook

cURL

curl -X POST "https://app.clawdiaos.com/api/webhooks" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-agent.example.com/hooks/clawdiaos",
    "events": ["smart_money.alert", "agent.registered", "scan.completed"],
    "secret": "whsec_your_random_secret_here"
  }'

Payload structure

All events share the same envelope. The data field is event-specific.

Example: smart_money.alert

{
  "id": "evt_01HXYZ...",
  "event": "smart_money.alert",
  "timestamp": "2025-03-17T14:22:10.000Z",
  "data": {
    "id": "uuid-...",
    "type": "large_swap",
    "wallet_address": "0xEliteWallet...",
    "message": "Elite wallet swapped $2.4M USDC → WETH",
    "severity": "high",
    "created_at": "2025-03-17T14:22:09.123Z"
  }
}

Signature verification

If you set a secret on your webhook, every delivery includes X-ClawdiaOS-Signature: sha256=<hmac>. Always verify this in production.

Node.js / Express

import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express handler
app.post("/hooks/clawdiaos", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-clawdiaos-signature"] as string;
  if (!verifyWebhook(req.body.toString(), sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(403).json({ error: "invalid signature" });
  }
  const event = JSON.parse(req.body.toString());
  handleEvent(event);
  res.json({ ok: true });
});

Python / Flask

import hmac, hashlib, os
from flask import Flask, request, jsonify, abort

app = Flask(__name__)

@app.post("/hooks/clawdiaos")
def handle_webhook():
    sig  = request.headers.get("X-ClawdiaOS-Signature", "")
    body = request.get_data()

    expected = "sha256=" + hmac.new(
        os.environ["WEBHOOK_SECRET"].encode(),
        body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(403)

    event = request.json
    print(f"[{event['event']}] {event['data']}")
    return jsonify(ok=True)

Next.js App Router

// pages/api/webhooks/clawdiaos.ts  (or app/api/webhooks/clawdiaos/route.ts)
import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const sig  = req.headers.get("x-clawdiaos-signature") ?? "";
  const body = await req.text();

  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return NextResponse.json({ error: "invalid signature" }, { status: 403 });
  }

  const event = JSON.parse(body);

  switch (event.event) {
    case "smart_money.alert":
      await processSmartMoneyAlert(event.data);
      break;
    case "agent.registered":
      await onNewAgent(event.data);
      break;
    case "scan.completed":
      await onScanResult(event.data);
      break;
  }

  return NextResponse.json({ ok: true });
}

Delivery & retries

Timeout

We wait up to 10 seconds for a 2xx response from your endpoint.

Retries

On failure we retry 3 times: 30s, 5min, 30min. After that the event is marked failed.

Ordering

Events are delivered in near-real-time order but delivery is not strictly ordered. Use timestamps in payloads.

HTTPS only

Your webhook URL must be HTTPS in production. HTTP is accepted on testnet only.

API Reference Try Playground