Anima Webhooks & Events

Overview

Use Figma Webhooks v2 to detect approved design changes and enqueue Anima generation. Figma supplies the event contract; this workflow does not invent an Anima webhook API.

Prerequisites

• Team-level Figma webhook permission, a publicly reachable HTTPS endpoint, and a webhook passcode stored in a secret manager rather than source or request logs.
• An allowlist mapping approved file keys and component node IDs to their generated output directories and responsible owners.
• A durable event-id/version store, queue with retry and dead-letter handling, and a staging workspace containing synthetic design data.
• A rate-limit budget, replay/duplicate policy, and an explicit approval gate before generated code can be merged or deployed.

Authentication

Register the webhook with an authorized Figma token and keep its passcode in the receiver's secret manager. The queued backend worker separately uses managed Anima and Figma credentials; neither credential belongs in the event payload.

Instructions

Step 1: Register Figma Webhook

# Figma Webhooks API (requires team-level access)
curl -X POST "https://api.figma.com/v2/webhooks" \
  -H "X-Figma-Token: ${FIGMA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "FILE_VERSION_UPDATE",
    "context": "team",
    "context_id": "YOUR_TEAM_ID",
    "endpoint": "https://your-server.com/webhooks/figma",
    "passcode": "your-webhook-secret",
    "description": "Trigger Anima code generation on design changes"
  }'

Step 2: Webhook Handler

// src/webhooks/figma-handler.ts
import express from 'express';
import crypto from 'node:crypto';

const router = express.Router();
declare const generationQueue: {
  enqueue(job: { fileKey: string; eventTimestamp: string }): Promise<void>;
};

interface FigmaWebhookEvent {
  event_type: 'FILE_VERSION_UPDATE' | 'FILE_UPDATE' | 'FILE_DELETE';
  file_key: string;
  timestamp: string;
  passcode: string;
}

router.post('/webhooks/figma', express.json(), async (req, res) => {
  const event = req.body as FigmaWebhookEvent;

  // Verify passcode
  const supplied = Buffer.from(event.passcode || '');
  const expected = Buffer.from(process.env.FIGMA_WEBHOOK_SECRET || '');
  if (supplied.length !== expected.length || !crypto.timingSafeEqual(supplied, expected)) {
    return res.status(400).json({ error: 'Invalid passcode' });
  }

  // Only process file version updates
  if (event.event_type !== 'FILE_VERSION_UPDATE') {
    return res.status(200).json({ skipped: true });
  }

  console.log({ eventType: event.event_type, fileKey: event.file_key });

  // Trigger async generation — respond immediately
  await generationQueue.enqueue({ fileKey: event.file_key, eventTimestamp: event.timestamp });
  res.status(200).json({ accepted: true });
});

export default router;

Error Handling

Verify the passcode before parsing or acting on design data, use an idempotency key based on the webhook/version identity, and never log file contents, triggerer handles, tokens, or full payloads. A failed regeneration must leave the last known-good generated revision intact.

Step 3: Figma Webhook Event Types

Tool Discipline

Use Read and Grep to inspect the existing integration and generated diff before changing anything. Use Write or Edit only inside the approved generated-code, test, or configuration paths. Use the declared Bash commands only for the explicit install, validation, or diagnostic steps in this workflow; never print tokens, source designs, generated source, or private website captures.

Output

• Figma webhook registration for design change detection
• Event handler triggering Anima code generation on file updates
• Rate-limited async regeneration pipeline

Examples

Register a staging webhook with a managed passcode and an endpoint dedicated to synthetic design fixtures:

curl -X POST "https://api.figma.com/v2/webhooks" \
  -H "X-Figma-Token: ${FIGMA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "FILE_VERSION_UPDATE",
    "context": "team",
    "context_id": "synthetic-team",
    "endpoint": "https://staging.example.invalid/webhooks/figma",
    "passcode": "'"${FIGMA_WEBHOOK_SECRET}"'",
    "description": "staging design sync"
  }'

Send one version-update fixture and confirm the endpoint returns immediately, queues exactly one allowlisted generation, applies rate limiting, and produces contacts_exported=0 (or the equivalent no-external-write assertion). The receipt should contain only the webhook/version identity, source allowlist result, generation status, artifact digest, and cleanup/rollback result.

Resources

• Figma Webhooks API
• Anima API