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

Failure	Required response
Passcode is missing or invalid	Return 400, enqueue nothing, and record only a redacted rejection reason.
Event is malformed, duplicated, stale, or outside the file/node allowlist	Acknowledge safely where appropriate, discard the event, and retain a deduplicated audit receipt.
Generation or downstream quality checks fail	Retry with bounded backoff, then move the event to a dead-letter queue; do not open a merge or deploy automatically.
Figma or Anima rate limit is reached	Honor the provider response, apply queue backpressure, and preserve event order for the same file.
File is deleted or access is revoked	Disable further generation for that source and require owner confirmation before cleanup or re-registration.

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

Event Type	Trigger	Use Case
FILE_VERSION_UPDATE	New version saved	Regenerate components
FILE_UPDATE	File modified (real-time)	Too frequent — use version instead
FILE_DELETE	File deleted	Clean up generated code
PING	Webhook health check	Validate receipt without enqueuing generation

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