Anima Webhooks Events

Anima Webhooks & Events

Overview

Anima doesn't have its own webhooks, but you can use Figma Webhooks (v2 API) to detect design changes and trigger Anima code generation automatically. This creates an event-driven design-to-code pipeline.

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.

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",
    "team_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 { Anima } from '@animaapp/anima-sdk';

const router = express.Router();
const anima = new Anima({ auth: { token: process.env.ANIMA_TOKEN! } });

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

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

  // Verify passcode
  if (event.passcode !== process.env.FIGMA_WEBHOOK_SECRET) {
    return res.status(401).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(`Design changed: ${event.file_name} by ${event.triggered_by.handle}`);

  // Trigger async generation — respond immediately
  regenerateComponents(event.file_key).catch(console.error);
  res.status(200).json({ accepted: true });
});

async function regenerateComponents(fileKey: string) {
  const COMPONENT_NODES = ['1:2', '3:4', '5:6']; // Your component node IDs

  for (const nodeId of COMPONENT_NODES) {
    try {
      const { files } = await anima.generateCode({
        fileKey,
        figmaToken: process.env.FIGMA_TOKEN!,
        nodesId: [nodeId],
        settings: { language: 'typescript', framework: 'react', styling: 'tailwind' },
      });
      console.log(`Regenerated node ${nodeId}: ${files.length} files`);
      await new Promise(r => setTimeout(r, 6000)); // Rate limit
    } catch (err) {
      console.error(`Failed to regenerate ${nodeId}:`, err);
    }
  }
}

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

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",
    "team_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

Next Steps

For performance optimization, see anima-performance-tuning.