​
Overview

There are three ways to interact with the Figma API through our platform:

​
Figma API Quirks

Every Figma REST API request requires a team ID. This is a unique identifier for your Figma team. Webhooks are created at the team level, so you/your users will need to provide this value when creating a webhook. We provide a helper function to retrieve the team ID for you. See below.

​
Creating a Webhook for a User

The SDK is strongly typed and uses Classes in the background to provide the easiest experience possible. Here’s how to create a webhook:

​
Step 1:

Team ID Retrieval: Figma’s REST API doesn’t support retrieving the team ID programmatically. You will need this value to interact with the API. The team ID can be found in the URL of your Figma team. Use our hook to redirect the user to obtain the teamID value.

import { getFigmaTeamIdRedirectUrl } from 'syncd-hooks';
...
// Note: this is not async
const teamIdRedirectUrl = getFigmaTeamIdRedirectUrl();
...
<a href={teamIdRedirectUrl}>Get Team ID</a>
...

Have your customers choose (physicaly click on the team they want) the team they want to integrate with. Then have them copy the URL at the top of the browser and paste it into your application.

​
Step 2:

Use the SDK to create a new webook for a user. If you don’t provide an external user, the webhook will be created for the user who the access token belongs to.

Example:

create-figma.ts
    /**
     * We use JSDocs in the SDK to give you the best experience possible.
     * If you need to know what a function does, you can hover over it in your IDE.
     * If you need to know why you need a projectId for example, you can hover over it.
     */
    const res = await syncdClient.providers.figma.webhooks.create({
      // This is a dummy URL. You will need to replace it with your own or your external user's URL.
      teamUrl: "https://www.figma.com/files/team/09834029834029/all-projects?fuid=02934820948234",
      callbackUrl: "https://api.my-api.com/api/webhooks/figma",
      // You can use this in the dashboard to easily identify the webhook.
      endpointName: `${user.id} - Figma Webhook`,
      endpoindDescription: "DEV - Figma Webhook",
      eventType: "FILE_UPDATE", // Fully typed
      // Syncd uses projects to group webhooks and users. You will need to create a project first and copy the ID.
      projectId: process.end.SYNCD_PROJECT_ID,
      accessToken: <your-users-access-token>,

      // This is an optional object that you can use to create an external user
      externalUser: {
        // If you do choose this option, you will need to provide a uniqueId
        uniqueId: user.id,
        firstName: user.firstName, // Optional
        lastName: user.lastName, // Optional

        // Any key value pairs you want to store with the user
        metadata: {
          email: "john@doe.com",
        },
      },
    });

Now you are done in a couple lines of code. You can head over to the dashboard to see the logs and webhook bodies.

​
Updating a Webhook for a User

If you don’t want to create a new webhook, you can update an existing one. This is useful if you want to change the callbackUrl or eventType. The resulting webhook will be under the same project and endpointID so you don’t need to worry about updating things in your database/storage.

​
Example Payloads

With each provider we have example payloads so you can test the webhook events. This can be useful for debugging and testing your application.

To import, each payload example starts with the provider name and then the event name. For example, figmaFileCommentEventExamplePayload. Use intelligent auto-complete in your IDE to find the payload you need.

Here’s an example of the Figma File Comment Example Payload (you can import as figmaFileCommentEventExamplePayload):

{
    comment: [
      {
        text: "TODO: \n",
      },
      {
        mention: "811724164054158337",
      },
      {
        text: "Change selection colors",
      },
    ],
    comment_id: "32",
    created_at: "2020-02-23T20:27:16Z",
    event_type: "FILE_COMMENT",
    file_key: "zH44k2FUM629Fa4EMShiHL",
    file_name: "Mockup library",
    mentions: [
      {
        id: "811724164054158337",
        handle: "Evan Wallace",
      },
    ],
    order_id: "23 ",
    parent_id: "",
    passcode: "secretpasscode",
    resolved_at: "",
    timestamp: "2020-02-23T20:27:16Z",
    triggered_by: {
      id: "813845097374535682",
      handle: "Dylan Field",
    },
    webhook_id: "22",
  };

​
Types

We also provide types for all supported event payloads. This can be helpful when you are consuming webhooks on your endpoint. Instead of the payload body being an any type, now you can do something like this:

import { TFigmaFileCommentEventPayload } from '@syncd-sdk';
...
// Now the body is fully typed
const body: TFigmaFileCommentEventPayload = await req.json();
...

Here is what the type looks like if you hover over it:

{
  comment: (
    | {
        text: string;
      }
    | {
        mention: string;
      }
  )[];
  comment_id: string;
  created_at: string;
  event_type: "FILE_COMMENT";
  file_key: string;
  file_name: string;
  mentions: {
    id: string;
    handle: string;
  }[];
  order_id: string;
  parent_id: string;
  passcode: string;
  resolved_at: string;
  timestamp: string;
  triggered_by: {
    id: string;
    handle: string;
  };
  webhook_id: string;
};

​
Zod Schemas - Coming Soon

This will allow you to validate the incoming webhook body against a schema. This can be useful for ensuring the body is correct before processing it.

​
Internal company webhooks

If you want to use Syncd as an internal webhook sending, regestration, and managment service, the dashboard has you covered. We handle and mange the access tokens with one click.

GitHub