Skip to main content

Webhooks

Configure webhooks to receive HTTP notifications when events occur in your Lucid workspace.

Events

EventDescription
receipt.createdNew inference receipt generated
epoch.anchoredEpoch anchored on Solana
passport.createdNew passport registered
passport.syncedPassport synced on-chain
agent.startedAgent execution began
agent.completedAgent execution finished
budget.warningSession budget at 80%
budget.exceededSession budget exceeded

Register a Webhook

const webhook = await lucid.webhooks.create({
  url: "https://your-app.com/webhooks/lucid",
  events: ["receipt.created", "epoch.anchored"],
  secret: "whsec_your-signing-secret",
});

Payload Format

{
  "id": "evt_abc123",
  "type": "receipt.created",
  "timestamp": "2026-02-24T10:30:00Z",
  "data": {
    "receiptId": "rec_xyz789",
    "model": "gpt-4o",
    "inputTokens": 150,
    "outputTokens": 320,
    "signatureValid": true
  }
}

Verify Signatures

Every webhook request includes an X-Lucid-Signature header. Always verify before processing:
import { createHmac, timingSafeEqual } from "crypto";

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

// In your Express handler:
app.post("/webhooks/lucid", (req, res) => {
  const sig = req.headers["x-lucid-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), sig, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { type, data } = req.body;
  console.log(`Received ${type}:`, data);
  res.status(200).send("OK");
});

Retry Policy

Failed deliveries (non-2xx responses) are retried with exponential backoff:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry12 hours
After 5 failed attempts, the webhook is disabled. Re-enable from the Dashboard or API.

Manage Webhooks

// List webhooks
const webhooks = await lucid.webhooks.list();

// Update events
await lucid.webhooks.update(webhook.id, {
  events: ["receipt.created", "epoch.anchored", "agent.completed"],
});

// Delete
await lucid.webhooks.delete(webhook.id);