figma-code-agent 1.0.0

package/knowledge/figma-api-webhooks.md

@@ -0,0 +1,876 @@
+# Figma Webhooks v2 Reference
+
+## Purpose
+
+Authoritative reference for Figma Webhooks v2 covering webhook scoping via `context` + `context_id`, all CRUD endpoints, event types with payload structures, operational considerations (passcode verification, retries, idempotency), and practical webhook listener patterns. This module documents the server-side integration for reacting to Figma file changes in real time.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Set up webhook listeners for Figma file change notifications
+- Create, update, or delete webhooks via the REST API
+- Handle webhook event payloads (FILE_UPDATE, LIBRARY_PUBLISH, etc.)
+- Verify webhook authenticity using passcode comparison
+- Understand retry behavior and operational requirements
+- Build automated pipelines triggered by Figma design changes
+
+---
+
+## Content
+
+### Webhooks v2 Overview
+
+Webhooks enable your server to receive HTTP POST notifications when specific events occur in Figma files, projects, or teams. Webhooks v2 uses a `context` + `context_id` scoping model that supports team-level, project-level, and file-level granularity.
+
+> **Critical:** Webhook creation uses `context` + `context_id` fields, NOT the deprecated `team_id` field. The `team_id` field in the WebhookV2 response object is a legacy read-only field (empty string for project/file-scoped webhooks).
+
+#### Scoping Model
+
+| Context | `context` value | `context_id` value | Who can create | Receives events for |
+|---------|----------------|-------------------|----------------|-------------------|
+| Team | `"team"` | Team ID | Team admins | All files available to team members (excludes invite-only project files) |
+| Project | `"project"` | Project ID | Users with edit access to project | All files in the project |
+| File | `"file"` | File key | Users with edit access to file | The specific file only |
+
+#### Webhook Limits
+
+| Context | Max webhooks per context |
+|---------|:------------------------:|
+| Team | 20 |
+| Project | 5 |
+| File | 3 |
+
+**File webhook totals by plan:**
+
+| Plan | Max file webhooks total |
+|------|:-----------------------:|
+| Professional | 150 |
+| Organization | 300 |
+| Enterprise | 600 |
+
+#### Webhook Statuses
+
+| Status | Description |
+|--------|-------------|
+| `ACTIVE` | The webhook is healthy and receives all events |
+| `PAUSED` | The webhook is paused and will not receive any events |
+
+> **Note:** You cannot programmatically set a webhook to an error state. Figma manages error states internally based on delivery failures.
+
+#### WebhookV2 Object
+
+```ts
+interface WebhookV2 {
+  /** Unique webhook identifier */
+  id: number;
+
+  /** The event type this webhook listens for */
+  event_type: WebhookV2Event;
+
+  /** Scoping context: "team", "project", or "file" */
+  context: 'team' | 'project' | 'file';
+
+  /** ID of the context (team ID, project ID, or file key) */
+  context_id: string;
+
+  /** Team subscription ID (empty string for project/file webhooks) */
+  team_id: string;
+
+  /** Team/organization plan API ID */
+  plan_api_id: string;
+
+  /** Current webhook status */
+  status: 'ACTIVE' | 'PAUSED';
+
+  /** OAuth application identifier (if created via OAuth) */
+  client_id: string;
+
+  /** Security passcode (empty in GET responses for security) */
+  passcode: string;
+
+  /** Target URL for webhook event delivery */
+  endpoint: string;
+
+  /** Optional user-provided description (max 140 characters) */
+  description: string;
+}
+```
+
+---
+
+### Webhook Endpoints
+
+All webhook endpoints use the `/v2/` prefix (unlike most Figma API endpoints which use `/v1/`).
+
+**Authentication:** All endpoints require a Figma API token (PAT or OAuth) with the appropriate scope.
+
+| Operation | Scope Required |
+|-----------|---------------|
+| Read webhooks | `webhooks:read` |
+| Create / Update / Delete | `webhooks:write` |
+
+**Rate limit tier:** All webhook endpoints are Tier 2.
+
+#### POST /v2/webhooks — Create Webhook
+
+Creates a new webhook subscription. On success, Figma immediately sends a `PING` event to the endpoint (unless `status` is set to `PAUSED`).
+
+```bash
+curl -X POST \
+  -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event_type": "FILE_UPDATE",
+    "context": "team",
+    "context_id": "123456",
+    "endpoint": "https://your-server.com/figma-webhook",
+    "passcode": "YOUR_WEBHOOK_PASSCODE"
+  }' \
+  "https://api.figma.com/v2/webhooks"
+```
+
+**Request body fields:**
+
+| Field | Type | Required | Description |
+|-------|------|:--------:|-------------|
+| `event_type` | string | Yes | Event type to subscribe to (see Event Types section) |
+| `context` | string | Yes | `"team"`, `"project"`, or `"file"` |
+| `context_id` | string | Yes | The ID of the team, project, or file |
+| `endpoint` | string | Yes | URL to receive webhook payloads (max 2048 characters) |
+| `passcode` | string | Yes | Secret passcode echoed back in payloads for verification (max 100 characters) |
+| `status` | string | No | Initial status: `"ACTIVE"` (default) or `"PAUSED"` |
+| `description` | string | No | Human-readable description (max 150 characters) |
+
+**Response:** Returns the created `WebhookV2` object.
+
+> **Important:** The endpoint must be ready to receive and acknowledge the `PING` event before or immediately after creation. If the PING fails, the webhook is still created but may be in a degraded state.
+
+#### GET /v2/webhooks/:webhook_id — Get Webhook
+
+Retrieves a single webhook by ID.
+
+```bash
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks/WEBHOOK_ID"
+```
+
+**Response:** Returns the `WebhookV2` object (with `passcode` as empty string for security).
+
+#### GET /v2/webhooks — List Webhooks
+
+Lists webhooks with optional filtering by context.
+
+```bash
+# List all webhooks for a team
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks?context=team&context_id=123456"
+
+# List all webhooks for a file
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks?context=file&context_id=FILE_KEY"
+```
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `context` | string | Filter by context type (`"team"`, `"project"`, `"file"`) |
+| `context_id` | string | Filter by context ID (used with `context`) |
+| `plan_api_id` | string | Filter by plan API ID (cannot combine with `context`/`context_id`) |
+| `cursor` | string | Pagination cursor from a previous response |
+
+**Response:**
+
+```ts
+interface ListWebhooksResponse {
+  webhooks: WebhookV2[];
+  pagination: {
+    next_page?: string;
+    prev_page?: string;
+  };
+}
+```
+
+> **Note:** The deprecated `GET /v2/teams/:team_id/webhooks` endpoint is replaced by `GET /v2/webhooks?context=team&context_id=TEAM_ID`.
+
+#### PUT /v2/webhooks/:webhook_id — Update Webhook
+
+Updates an existing webhook. Only include the fields you want to change.
+
+```bash
+curl -X PUT \
+  -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event_type": "FILE_VERSION_UPDATE",
+    "status": "PAUSED"
+  }' \
+  "https://api.figma.com/v2/webhooks/WEBHOOK_ID"
+```
+
+**Updatable fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `event_type` | string | Change the event type |
+| `endpoint` | string | Change the delivery URL |
+| `passcode` | string | Change the verification passcode |
+| `status` | string | `"ACTIVE"` or `"PAUSED"` (cannot set to error state) |
+| `description` | string | Change the description |
+
+**Response:** Returns the updated `WebhookV2` object.
+
+#### DELETE /v2/webhooks/:webhook_id — Delete Webhook
+
+Permanently deletes a webhook. This operation is irreversible.
+
+```bash
+curl -X DELETE \
+  -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks/WEBHOOK_ID"
+```
+
+**Response:** Returns the deleted `WebhookV2` object.
+
+#### GET /v2/webhooks/:webhook_id/requests — Debug Webhook Activity
+
+Retrieves the delivery history for a webhook from the last 7 days. Useful for debugging delivery issues.
+
+```bash
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks/WEBHOOK_ID/requests"
+```
+
+---
+
+### Event Types
+
+Each webhook subscribes to exactly one event type. To listen for multiple event types, create multiple webhooks.
+
+#### PING
+
+Sent automatically when a webhook is created (unless created with `status: "PAUSED"`). Used to verify that your endpoint is configured correctly.
+
+**Payload:**
+
+```json
+{
+  "event_type": "PING",
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "webhook_id": 12345
+}
+```
+
+> **Important:** The PING event does NOT include `file_key` or `file_name`. It is the only event type with this minimal payload structure.
+
+#### FILE_UPDATE
+
+Triggers within **30 minutes of editing inactivity** in a file. This is a debounced event — it does not fire on every keystroke or edit, but after the file has been idle for a period.
+
+**Payload:**
+
+```json
+{
+  "event_type": "FILE_UPDATE",
+  "file_key": "abc123DEF456",
+  "file_name": "Design System v2",
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "webhook_id": 12345
+}
+```
+
+#### FILE_DELETE
+
+Triggers when a file is deleted. Does NOT trigger for files within deleted folders — only for directly deleted files.
+
+**Payload:**
+
+```json
+{
+  "event_type": "FILE_DELETE",
+  "file_key": "abc123DEF456",
+  "file_name": "Deleted Design",
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "triggered_by": {
+    "id": "12345",
+    "handle": "designer@example.com"
+  },
+  "webhook_id": 12345
+}
+```
+
+#### FILE_VERSION_UPDATE
+
+Triggers when a user creates a named version in the file's version history.
+
+**Payload:**
+
+```json
+{
+  "event_type": "FILE_VERSION_UPDATE",
+  "file_key": "abc123DEF456",
+  "file_name": "Design System v2",
+  "created_at": "2026-01-15T10:30:00Z",
+  "version_id": "987654321",
+  "label": "v2.1 Release",
+  "description": "Updated button variants and color tokens",
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "triggered_by": {
+    "id": "12345",
+    "handle": "designer@example.com"
+  },
+  "webhook_id": 12345
+}
+```
+
+#### FILE_COMMENT
+
+Triggers when a user posts a comment on a file.
+
+**Payload:**
+
+```json
+{
+  "event_type": "FILE_COMMENT",
+  "file_key": "abc123DEF456",
+  "file_name": "Design System v2",
+  "comment": [
+    { "text": "Can we update the " },
+    { "mention": "67890" },
+    { "text": " color here?" }
+  ],
+  "comment_id": 1001,
+  "mentions": [
+    { "id": "67890", "handle": "dev@example.com" }
+  ],
+  "order_id": 5,
+  "parent_id": null,
+  "created_at": "2026-01-15T10:30:00Z",
+  "resolved_at": null,
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "triggered_by": {
+    "id": "12345",
+    "handle": "designer@example.com"
+  },
+  "webhook_id": 12345
+}
+```
+
+**Comment-specific fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `comment` | CommentFragment[] | Array of text and mention fragments |
+| `comment_id` | number | Unique comment identifier |
+| `mentions` | User[] | Array of mentioned users |
+| `order_id` | number | Top-level comment display number |
+| `parent_id` | number or null | Parent comment ID if this is a reply |
+| `created_at` | string | Comment creation timestamp |
+| `resolved_at` | string or null | When the comment was resolved (null if unresolved) |
+
+#### LIBRARY_PUBLISH
+
+Triggers when a library file is published. Large publications may generate multiple events split by asset type.
+
+**Payload:**
+
+```json
+{
+  "event_type": "LIBRARY_PUBLISH",
+  "file_key": "abc123DEF456",
+  "file_name": "Design System v2",
+  "description": "Added new icon set and updated color tokens",
+  "created_components": [
+    { "key": "comp:abc", "name": "Icon/Arrow" }
+  ],
+  "created_styles": [],
+  "created_variables": [
+    { "key": "var:def", "name": "color/accent" }
+  ],
+  "modified_components": [
+    { "key": "comp:xyz", "name": "Button/Primary" }
+  ],
+  "modified_styles": [
+    { "key": "style:123", "name": "Heading/H1" }
+  ],
+  "modified_variables": [],
+  "deleted_components": [],
+  "deleted_styles": [],
+  "deleted_variables": [],
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "triggered_by": {
+    "id": "12345",
+    "handle": "designer@example.com"
+  },
+  "webhook_id": 12345
+}
+```
+
+**Library item data:**
+
+```ts
+interface LibraryItemData {
+  key: string;   // Unique key for the library item
+  name: string;  // Display name
+}
+```
+
+The `created_*`, `modified_*`, and `deleted_*` arrays provide granular detail about what changed in the library publish, including components, styles, and variables.
+
+#### DEV_MODE_STATUS_UPDATE
+
+Triggers when the Dev Mode status changes for a layer in a file (e.g., marked as "Ready for Dev" or "Completed").
+
+**Payload:**
+
+```json
+{
+  "event_type": "DEV_MODE_STATUS_UPDATE",
+  "file_key": "abc123DEF456",
+  "node_id": "1:234",
+  "status": "READY_FOR_DEV",
+  "change_message": "Header component ready for implementation",
+  "related_links": [
+    {
+      "id": "dev-resource-id",
+      "name": "React Component",
+      "url": "https://github.com/org/repo/blob/main/src/Header.tsx",
+      "file_key": "abc123DEF456",
+      "node_id": "1:234"
+    }
+  ],
+  "passcode": "YOUR_WEBHOOK_PASSCODE",
+  "timestamp": "2026-01-15T10:30:00Z",
+  "triggered_by": {
+    "id": "12345",
+    "handle": "designer@example.com"
+  },
+  "webhook_id": 12345
+}
+```
+
+**Status values:** `NONE`, `READY_FOR_DEV`, `COMPLETED`
+
+#### Common Payload Fields
+
+Every webhook payload includes these fields:
+
+| Field | Type | Present in | Description |
+|-------|------|-----------|-------------|
+| `event_type` | string | All events | The event type identifier |
+| `passcode` | string | All events | The passcode you provided at webhook creation (for verification) |
+| `timestamp` | string | All events | UTC ISO 8601 timestamp of the event |
+| `webhook_id` | number | All events | The webhook ID that generated this event |
+| `file_key` | string | All except PING | The file key that triggered the event |
+| `file_name` | string | All except PING and DEV_MODE_STATUS_UPDATE | The file name |
+| `triggered_by` | User | All except PING and FILE_UPDATE | The user who triggered the event |
+
+---
+
+### Operational Considerations
+
+#### Passcode Verification
+
+Every webhook payload includes the `passcode` field, which echoes back the secret you provided when creating the webhook. **Always verify this passcode** to confirm the request originated from Figma.
+
+```ts
+function verifyWebhookPasscode(
+  payload: Record<string, any>,
+  expectedPasscode: string
+): boolean {
+  return payload.passcode === expectedPasscode;
+}
+```
+
+> **Warning:** The passcode is NOT a cryptographic signature. It is a shared secret sent in the request body. Always use HTTPS for your webhook endpoint to protect the passcode in transit.
+
+#### Response Requirements
+
+Your webhook endpoint must respond with a **200 OK** status code **quickly** (ideally within a few seconds). Figma interprets slow responses or non-200 status codes as failures and will initiate retry logic.
+
+**Best practice:** Accept the webhook payload, return 200 immediately, then process the event asynchronously:
+
+```ts
+// Good: Respond immediately, process later
+app.post('/figma-webhook', (req, res) => {
+  res.status(200).send('OK');
+  processEventAsync(req.body); // Fire-and-forget
+});
+
+// Bad: Process synchronously before responding
+app.post('/figma-webhook', async (req, res) => {
+  await heavyProcessing(req.body); // May timeout
+  res.status(200).send('OK');
+});
+```
+
+#### Retry Behavior
+
+When Figma fails to deliver a webhook event (non-200 response or timeout), it retries with **exponential backoff**:
+
+| Retry | Delay after failure |
+|:-----:|:-------------------:|
+| 1st | 5 minutes |
+| 2nd | 30 minutes |
+| 3rd | 3 hours |
+
+After **3 failed retries**, the delivery is abandoned for that event. Figma does not retry further for that specific event.
+
+#### Idempotency
+
+The same event may be delivered more than once (e.g., if your server responded slowly and Figma retried). **Always handle webhook events idempotently:**
+
+- Use `webhook_id` + `timestamp` + `event_type` as a deduplication key
+- Track processed event identifiers in a store (database, Redis, etc.)
+- Ensure that processing the same event twice produces the same result
+
+```ts
+const processedEvents = new Set<string>();
+
+function handleWebhookEvent(payload: Record<string, any>): boolean {
+  const eventKey = `${payload.webhook_id}:${payload.event_type}:${payload.timestamp}`;
+
+  if (processedEvents.has(eventKey)) {
+    return false; // Already processed — skip
+  }
+
+  processedEvents.add(eventKey);
+  return true; // Process this event
+}
+```
+
+> **Note:** In production, use a persistent store (database or cache with TTL) instead of an in-memory Set to survive server restarts.
+
+#### Webhook Health and Disabling
+
+Figma monitors webhook delivery success. After repeated delivery failures, Figma may internally flag the webhook. Use the requests endpoint to debug:
+
+```bash
+# Check delivery history for the last 7 days
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v2/webhooks/WEBHOOK_ID/requests"
+```
+
+If a webhook becomes unreliable:
+1. Check the requests endpoint for error details
+2. Fix the endpoint issue
+3. If paused, update the webhook status back to `ACTIVE`
+
+#### Team Context Notification Scope
+
+Team-scoped webhooks receive events for:
+- Files available to all team members
+- Files in view-only projects
+
+Team-scoped webhooks do **NOT** receive events for:
+- Files in invite-only projects (use project-scoped or file-scoped webhooks for these)
+
+---
+
+### Practical Patterns
+
+#### Setting Up a Webhook Listener (Express)
+
+```ts
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+const WEBHOOK_PASSCODE = process.env.FIGMA_WEBHOOK_PASSCODE!;
+
+app.post('/figma-webhook', (req, res) => {
+  const payload = req.body;
+
+  // 1. Verify passcode
+  if (payload.passcode !== WEBHOOK_PASSCODE) {
+    console.warn('Invalid webhook passcode — rejecting request');
+    res.status(401).send('Unauthorized');
+    return;
+  }
+
+  // 2. Respond immediately
+  res.status(200).send('OK');
+
+  // 3. Handle event asynchronously
+  handleFigmaEvent(payload).catch(err => {
+    console.error('Webhook processing error:', err);
+  });
+});
+
+async function handleFigmaEvent(payload: Record<string, any>): Promise<void> {
+  switch (payload.event_type) {
+    case 'PING':
+      console.log('Webhook verified:', payload.webhook_id);
+      break;
+
+    case 'FILE_UPDATE':
+      console.log(`File updated: ${payload.file_name} (${payload.file_key})`);
+      await syncFileChanges(payload.file_key);
+      break;
+
+    case 'FILE_VERSION_UPDATE':
+      console.log(`New version: ${payload.label} for ${payload.file_name}`);
+      await processNewVersion(payload.file_key, payload.version_id);
+      break;
+
+    case 'LIBRARY_PUBLISH':
+      console.log(`Library published: ${payload.file_name}`);
+      await syncLibraryChanges(payload);
+      break;
+
+    case 'FILE_COMMENT':
+      console.log(`Comment on ${payload.file_name} by ${payload.triggered_by.handle}`);
+      await notifyTeam(payload);
+      break;
+
+    case 'FILE_DELETE':
+      console.log(`File deleted: ${payload.file_name}`);
+      await handleFileDeletion(payload.file_key);
+      break;
+
+    case 'DEV_MODE_STATUS_UPDATE':
+      console.log(`Dev status changed: ${payload.status} for node ${payload.node_id}`);
+      await handleDevStatusChange(payload);
+      break;
+
+    default:
+      console.warn('Unknown event type:', payload.event_type);
+  }
+}
+
+app.listen(3000, () => console.log('Webhook listener running on port 3000'));
+```
+
+#### Setting Up a Webhook Listener (Next.js API Route)
+
+```ts
+// app/api/figma-webhook/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+const WEBHOOK_PASSCODE = process.env.FIGMA_WEBHOOK_PASSCODE!;
+
+export async function POST(request: NextRequest) {
+  const payload = await request.json();
+
+  // Verify passcode
+  if (payload.passcode !== WEBHOOK_PASSCODE) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Respond immediately — Next.js edge/serverless functions have timeouts
+  // Queue async processing to a background job system if heavy processing needed
+
+  switch (payload.event_type) {
+    case 'PING':
+      console.log('Webhook verified:', payload.webhook_id);
+      break;
+
+    case 'FILE_UPDATE':
+      // Queue for background processing
+      await queueJob('figma-file-sync', { fileKey: payload.file_key });
+      break;
+
+    case 'LIBRARY_PUBLISH':
+      await queueJob('figma-token-sync', {
+        fileKey: payload.file_key,
+        createdVariables: payload.created_variables,
+        modifiedVariables: payload.modified_variables,
+        deletedVariables: payload.deleted_variables,
+      });
+      break;
+  }
+
+  return NextResponse.json({ received: true }, { status: 200 });
+}
+```
+
+#### Creating a Webhook Programmatically
+
+```ts
+async function createFigmaWebhook(options: {
+  eventType: string;
+  context: 'team' | 'project' | 'file';
+  contextId: string;
+  endpoint: string;
+  passcode: string;
+  description?: string;
+}): Promise<WebhookV2> {
+  const response = await fetch('https://api.figma.com/v2/webhooks', {
+    method: 'POST',
+    headers: {
+      'X-Figma-Token': process.env.FIGMA_TOKEN!,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      event_type: options.eventType,
+      context: options.context,
+      context_id: options.contextId,
+      endpoint: options.endpoint,
+      passcode: options.passcode,
+      description: options.description,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(`Failed to create webhook: ${response.status} ${JSON.stringify(error)}`);
+  }
+
+  return response.json();
+}
+
+// Example: Listen for file updates on a team
+const webhook = await createFigmaWebhook({
+  eventType: 'FILE_UPDATE',
+  context: 'team',
+  contextId: '123456',
+  endpoint: 'https://your-server.com/figma-webhook',
+  passcode: process.env.FIGMA_WEBHOOK_PASSCODE!,
+  description: 'Design-to-code sync trigger',
+});
+
+console.log('Webhook created:', webhook.id);
+```
+
+#### Processing FILE_UPDATE for Design-to-Code Sync
+
+```ts
+async function syncFileChanges(fileKey: string): Promise<void> {
+  // 1. Fetch the latest file version
+  const fileRes = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}?depth=2`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const file = await fileRes.json();
+
+  // 2. Compare with cached version
+  const cachedVersion = await getStoredVersion(fileKey);
+  if (file.version === cachedVersion) {
+    console.log('No changes detected (same version)');
+    return;
+  }
+
+  // 3. Extract updated components and tokens
+  const components = findComponents(file.document);
+  const tokens = await extractTokens(fileKey);
+
+  // 4. Regenerate code for changed components
+  for (const component of components) {
+    await generateCode(component, tokens);
+  }
+
+  // 5. Update stored version
+  await storeVersion(fileKey, file.version);
+  console.log(`Synced ${components.length} components from ${file.name}`);
+}
+```
+
+#### Processing LIBRARY_PUBLISH for Token Sync
+
+```ts
+async function syncLibraryChanges(payload: Record<string, any>): Promise<void> {
+  const { file_key, created_variables, modified_variables, deleted_variables } = payload;
+
+  const hasVariableChanges =
+    created_variables?.length > 0 ||
+    modified_variables?.length > 0 ||
+    deleted_variables?.length > 0;
+
+  if (!hasVariableChanges) {
+    console.log('No variable changes in this publish — skipping token sync');
+    return;
+  }
+
+  // Fetch the latest variables from the file
+  const varsRes = await fetch(
+    `https://api.figma.com/v1/files/${file_key}/variables/local`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const { meta } = await varsRes.json();
+
+  // Regenerate CSS custom properties
+  const cssOutput = generateCSSVariables(meta.variables, meta.variableCollections);
+
+  // Write to tokens file
+  await writeTokensFile(cssOutput);
+
+  console.log(`Token sync complete: ${created_variables?.length || 0} created, ` +
+    `${modified_variables?.length || 0} modified, ${deleted_variables?.length || 0} deleted`);
+}
+```
+
+#### Managing Webhooks Lifecycle
+
+```ts
+// List all webhooks for a team
+async function listTeamWebhooks(teamId: string): Promise<WebhookV2[]> {
+  const res = await fetch(
+    `https://api.figma.com/v2/webhooks?context=team&context_id=${teamId}`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const data = await res.json();
+  return data.webhooks;
+}
+
+// Pause a webhook
+async function pauseWebhook(webhookId: number): Promise<void> {
+  await fetch(`https://api.figma.com/v2/webhooks/${webhookId}`, {
+    method: 'PUT',
+    headers: {
+      'X-Figma-Token': process.env.FIGMA_TOKEN!,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ status: 'PAUSED' }),
+  });
+}
+
+// Resume a webhook
+async function resumeWebhook(webhookId: number): Promise<void> {
+  await fetch(`https://api.figma.com/v2/webhooks/${webhookId}`, {
+    method: 'PUT',
+    headers: {
+      'X-Figma-Token': process.env.FIGMA_TOKEN!,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ status: 'ACTIVE' }),
+  });
+}
+
+// Delete a webhook
+async function deleteWebhook(webhookId: number): Promise<void> {
+  await fetch(`https://api.figma.com/v2/webhooks/${webhookId}`, {
+    method: 'DELETE',
+    headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! },
+  });
+}
+```
+
+---
+
+### Error Handling
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `400` | Invalid parameters (bad context, invalid event_type, endpoint too long) | Check request body against field constraints |
+| `401` | Authentication failed | Verify token and `webhooks:read` or `webhooks:write` scope |
+| `403` | Insufficient permissions (not a team admin for team context, no edit access for project/file context) | Confirm appropriate permissions for the webhook context |
+| `404` | Webhook not found | Verify the webhook ID exists |
+| `429` | Rate limited | Use `Retry-After` header. See `figma-api-rest.md` for backoff strategy |
+
+---
+
+## Cross-References
+
+- **`figma-api-rest.md`** — Core REST API reference (authentication, rate limits, file endpoints, node structure)
+- **`figma-api-variables.md`** — Variables API for design tokens (consumed by LIBRARY_PUBLISH sync patterns)
+- **`figma-api-plugin.md`** — Plugin API for in-editor access (alternative to webhook-triggered server-side processing)
+- **`figma-api-devmode.md`** — Dev Mode and Dev Resources (DEV_MODE_STATUS_UPDATE event, Dev Resources linking)
+- **`design-tokens.md`** — Token extraction strategies (used in LIBRARY_PUBLISH token sync pipelines)