Lucidchart Webhooks & Events

Overview

Lucidchart delivers real-time webhook notifications when documents, shapes, and collaboration states change across your organization's diagramming workspace. These events power integrations such as auto-archiving diagrams to Confluence when finalized, notifying Slack channels when collaborators join a shared document, triggering CI pipelines when architecture diagrams are updated, and maintaining audit logs of all document access. Payloads are signed JSON delivered over HTTPS using a webhook signing secret.

Prerequisites

• A Lucid developer account with an OAuth2 app registered at developer.lucid.co
• Webhook endpoint URL accessible over HTTPS (TLS 1.2+)
• Webhook signing secret from the Lucid app settings (LUCIDWEBHOOKSECRET)
• Express.js with raw body parsing for signature verification

Webhook Registration

import axios from "axios";

const res = await axios.post(
  "https://api.lucid.co/v1/webhooks",
  {
    callbackUrl: "https://your-app.com/webhooks/lucidchart",
    events: ["document.created", "document.updated", "document.shared",
             "shape.added", "collaborator.joined"],
    scope: "account",
  },
  { headers: { Authorization: `Bearer ${process.env.LUCID_ACCESS_TOKEN}`,
               "Lucid-Api-Version": "1" } }
);
console.log("Webhook ID:", res.data.webhookId);

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyLucidSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-lucid-signature"] as string;
  const requestId = req.headers["x-lucid-request-id"] as string;
  if (!signature || !requestId) return res.status(401).send("Missing signature");

  const expected = crypto
    .createHmac("sha256", process.env.LUCID_WEBHOOK_SECRET!)
    .update((req as any).rawBody)
    .digest("base64");

  if (!crypto.timingSafeEqual(Buffer.from(signature, "base64"), Buffer.from(expected, "base64"))) {
    return res.status(403).send("Invalid signature");
  }
  next();
}

Event Handler

app.post("/webhooks/lucidchart", verifyLucidSignature, (req, res) => {
  const { eventType, data, timestamp } = req.body;

  switch (eventType) {
    case "document.created":
      console.log(`New doc: "${data.title}" by ${data.creatorId} in ${data.folderId}`);
      break;
    case "document.updated":
      console.log(`Doc updated: ${data.documentId}, pages: ${data.pageCount}`);
      break;
    case "document.shared":
      console.log(`Doc shared: ${data.documentId} → ${data.recipientEmail} (${data.permission})`);
      break;
    case "shape.added":
      console.log(`Shape: ${data.shapeType} on page ${data.pageId} of doc ${data.documentId}`);
      break;
    case "collaborator.joined":
      console.log(`${data.userId} joined doc ${data.documentId} as ${data.role}`);
      break;
    default:
      console.warn(`Unhandled event: ${eventType}`);
  }
  res.status(200).json({ ok: true });
});

Event Types

Retry & Idempotency

const seen = new Set<string>();

function ensureIdempotent(req: Request, res: Response, next: NextFunction) {
  const requestId = req.headers["x-lucid-request-id"] as string;
  if (seen.has(requestId)) {
    return res.status(200).json({ duplicate: true });
  }
  seen.add(requestId);
  next();
}
// Lucid retries failed deliveries 3 times with exponential backoff (1 min, 5 min, 30 min).
// After 3 consecutive failures the webhook is marked inactive and must be re-enabled via API.

Error Handling

Resources

• Lucid Developer Reference

Next Steps

See lucidchart-security-basics.