API Request
```
Loading...
```
Webhooks V2Getting started
IMPORTANT: Webhooks V2 is still in open beta. Features and functions may change as we respond to feedback. Figma will attempt to keep APIs backwards compatible.
Webhooks allow you to observe when specific events happen in files. For example: a collaborator comments on a file, or you add a new version to a file's history.\
Using these events as triggers, you can build integrations with other applications. This can help to improve workflows, or extend the functionality of your design system.
Webhooks are attached to a specific team. All admins of that team can create and manage webhooks for the team. There is a limit of 20 webhooks per team. You can assign a certain event trigger to each webhook.
* Webhooks will notify for files that are available to everyone on the team, or are in[ view-only projects](https://help.figma.com/hc/en-us/articles/360038512473).
* Webhooks will not notify for files in [invite-only projects.](https://help.figma.com/hc/en-us/articles/360038512473)
Every payload (expect for PING) will contain the file name, file key and information related to the event triggered. This allows you to see which file triggered the event. Figma does not currently have an interface for webhooks. At the moment, you must create, modify, and delete webhooks through the webhooks API.
To get started with webhooks:\
\
Setup your local webserver and expose the endpoint\
Figma recommends using a tool similar to [ngrok](https://ngrok.com) to expose a public URL for your local webserver.\
\
Configure your server to handle POST requests with a JSON payload\
Your server should return the status code 200 OK when it receives a webhook request. If it returns another status code, or takes too long, the Figma API will treat this as an error. Figma retries failed requests 3 times with an exponential backoff strategy.
* The first retry occurs 5 minutes after the first failure.
* The second retry occurs 30 minutes after the second failure.
* The final retry occurs 3 hours after the third failure.
Figma does not currently deactivate endpoints with frequent errors.\
\
Create your webhook\
Use the [POST Webhook](https://www.figma.com/developers/api#webhooks-v2-post-endpoint) endpoint to attach a webhook to a team. You will need to be an admin of the team to create a webhook. If you are successful, you will receive a PING event. This means your webhook is working and will receive any updates.
If you are having problems with your webhook, you can query the[webhook requests endpoint](https://www.figma.com/developers/api#webhooks-v2-requests-endpoint). This will list all requests and responses within the past seven days.Events
| Event name | Trigger condition |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PING | Triggers when a webhook is created. Used for debugging. Cannot be subscribed to, all webhooks will recieve PING events. |
| FILE\_UPDATE | Triggers whenever a file saves. This occurs whenever a file is closed or within 30 seconds after changes have been made. |
| FILE\_VERSION\_UPDATE | Triggers whenever a named version is created in the version history of a file. |
| FILE\_DELETE | Triggers whenever a file has been deleted. If you subscribe to FILE\_UPDATE, you automatically get these notifications. Note that this does not trigger on all files within a folder, if the folder is deleted. |
| LIBRARY\_PUBLISH | Triggers whenever a library file is published. |
| FILE\_COMMENT | Triggers when someone comments on a file. |
Payloads
| Type | Properties |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PING | Debug event triggered whenever a webhook is created. Use this to verify that your endpoint was setup correctly.event\_typeStringThe type of event that triggered this webhook callpasscodeStringThe passcode specified when the webhook was created, should match what was initially providedtimestampStringUTC ISO 8601 timestamp of when the event was triggered.webhook\_idNumberThe id of the webhook that caused the callback> Example |
| FILE\_UPDATE | Triggers whenever a file is saved. This occurs if a file is closed or within 30 seconds after changes are made.
This is useful when you want to stay up-to-date with the contents of a file. For example, you could generate a static website from your Figma document and keep it always up-to-date with this webhook.event\_typeStringThe type of event that triggered this webhook callfile\_keyStringThe key of the file that was updatedfile\_nameStringThe name of the file that was updatedpasscodeStringThe passcode specified when the webhook was created, should match what was initially providedtimestampStringUTC ISO 8601 timestamp of when the event was triggered.webhook\_idNumberThe id of the webhook that caused the callback> Example
|
| FILE\_DELETE | Triggers whenever a file is trashed. Note if a folder is deleted, this event will not trigger for files within the folder.
This event will also be sent out to webhooks that subscribe to FILE\_UPDATE.event\_typeStringThe type of event that triggered this webhook callfile\_keyStringThe key of the file that was updatedfile\_nameStringThe name of the file that was updatedpasscodeStringThe passcode specified when the webhook was created, should match what was initially providedtimestampStringUTC ISO 8601 timestamp of when the event was triggered.triggered\_byUserThe user that deleted the file and triggered this eventwebhook\_idNumberThe id of the webhook that caused the callback> Example
|
| FILE\_VERSION\_UPDATE | Triggers whenever a user creates a named version in the version history of a file.
This is useful for workflow integrations. For example, suppose you have a Figma document with icon assets. When the design for an asset is updated and ready to publish, you can have a member of the team tag that version in the version history and then use this webhook event to generate and deploy your new asset version.created\_atStringUTC ISO 8601 timestamp of when the version was createddescriptionStringDesciption of the version in the version historyevent\_typeStringThe type of event that triggered this webhook callfile\_keyStringThe key of the file that was updatedfile\_nameStringThe name of the file that was updatedlabelStringLable of the version in the version historypasscodeStringThe passcode specified when the webhook was created, should match what was initially providedtimestampStringUTC ISO 8601 timestamp of when the event was triggeredtriggered\_byUserThe user that created the named version and triggered this eventversion\_idStringId of the published versionwebhook\_idNumberThe id of the webhook that caused the callback> Example
|
| LIBRARY\_PUBLISH | Triggers whenever a user publishes a library file.
This is useful for workflow integrations. This webhook could integrate with Slack, Asana or Jira, notifying designers to modify their assets when new components are published.created\_componentsComponentData\[]Components that were created by library publishdeleted\_componentsComponentData\[]Components that were deleted by library publishdescriptionStringDescription of the library publishevent\_typeStringThe type of event that triggered this webhook callfile\_keyStringThe key of the file that was updatedfile\_nameStringThe name of the file that was updatedmodified\_componentsComponentData\[]Components that were modified by the library publishpasscodeStringThe passcode specified when the webhook was created, should match what was initially providedtimestampStringUTC ISO 8601 timestamp of when the event was triggeredtriggered\_byUserThe user that published the library and triggered this event> Example
|
| FILE\_COMMENT | Triggers whenever a user comments on a file.
This webhook could integrate with Asana or Jira and automatically create tasks whenever a user comments. It could also integrate with Slack and notify mentioned users.
The contents of a comment is returned in an array of CommentFragment. A CommentFragment either contains a text of mention field. A text field contains raw comment text with formatting derivatives, newlines will be encoded as \n, etc.
Text fields can also contain emojis, which are always encoded as a separate fragment and are surrounded by two : characters. Mention fields occur if a user types @OtherUser in their comment. A mention contains the userid of the mentioned user. All mentioned users are added to the mentioned array field, where additional user information is included.commentCommentFragment\[]Contents of the comment itselfcomment\_idNumberUnique identifier for commentcreated\_atStringThe UTC ISO 8601 time at which the comment was leftevent\_typeStringThe type of event that triggered this webhook callfile\_keyStringThe key of the file that was updatedfile\_nameStringThe name of the file that was updatedmentionsUser\[]Users that were mentioned in the commentorder\_idNumberOnly set for top level comments. The number displayed with the comment in the UIparent\_idNumberIf present, the id of the comment to which this is the replypasscodeStringThe passcode specified when the webhook was created, should match what was initially providedresolved\_atStringIf set, the UTC ISO 8601 time the comment was resolvedtimestampStringUTC ISO 8601 timestamp of when the event was triggeredtriggered\_byUserThe user that made the comment and triggered the event> Example
|
Types
| Name | Properties |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| WebhookV2A description of an HTTP webhook (from Figma back to your application) | idStringThe ID of the webhookevent\_type[WebhookV2Event](https://www.figma.com/developers/api#webhookv2event-type)The event this webhook triggers onteam\_idStringThe team id you are subscribed to for updatesstatus[WebhookV2Status](https://www.figma.com/developers/api#webhookv2status-type)The current status of the webhookclient\_idStringThe client ID of the OAuth application that registered this webhook, if anypasscodeStringThe passcode that will be passed back to the webhook endpointendpointStringThe endpoint that will be hit when the webhook is triggereddescriptionStringOptional user-provided description or name for the webhook. This is provided to help make maintaining a number of webhooks more convenient. Max length 140 characters. |
| WebhookV2RequestInformation regarding the most recent interactions sent to a webhook endpoint | webhook\_idStringThe ID of the webhook the requests were sent torequest\_info[WebhookV2RequestInfo](https://www.figma.com/developers/api#webhookv2requestinfo-type)Information regarding the request sent to the webhook endpointresponse\_info[WebhookV2ResponseInfo](https://www.figma.com/developers/api#webhookv2responseinfo-type)Information regarding the response sent back from the webhook endpoint. NULL if no response was received.error\_msgStringError message for this request. NULL if no error occured. |
| WebhookV2RequestInfoInformation regarding the request sent to a webhook endpoint | endpointStringThe actual endpoint the request was sent topayload[Payload](https://www.figma.com/developers/api#payload-type)The contents of the request that was sent to the endpointsent\_atStringUTC ISO 8601 timestamp of when the request was sent |
| WebhookV2ResponseInfoInformation regarding the reply sent back from a webhook endpoint | statusStringHTTP status code of the responsereceived\_atStringThe UTC ISO 8601 time when the response was received |
| WebhookV2EventAn enum representing the possible events that a webhook can subscribe to | A webhook can subscribe to all events listed in the events section except the PING event. |
| WebhookV2StatusAn enum representing the possible statuses you can set a webhook to | ACTIVE: The webhook is healthy and receive all events
PAUSED: The webhook is paused and will not receive any events
|
| ComponentDataAn object representing the component information in the payload of the LIBRARY\_PUBLISH event | keyStringUnique identifier of componentnameStringName of component |
| CommentFragmentAn object representing a fragment of a comment left by a user, used in the payload of the FILE\_COMMENT event. Note only ONE of the fields below will be set | textStringComment text that is set if a fragment is text basedmentionStringUser id that is set if a fragment refers to a user mention |
EndpointsYou can use the following Webhooks via the Figma API:POST webhook
Create a new webhook which will call the specified endpoint when the event triggers. By default, this webhook will automatically send a PING event to the endpoint when it is created. If this behavior is not desired, you can create the webhook and set the status to PAUSED and reactivate it later.
HTTP Endpoint
POST/v2/webhooks
| Body parameters | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| event\_type | [WebhookV2Event](https://www.figma.com/developers/api#webhookv2event-type)The type of event that will trigger this webhook to fire |
| team\_id | StringTeam id to receive updates about |
| endpoint | StringThe HTTP endpoint that will receive a POST request when the event triggers. Max length 2048 characters. |
| passcode | StringString that will be passed back to your webhook endpoint to verify that it is being called by Figma. Max length 100 characters. |
| status | [WebhookV2Status](https://www.figma.com/developers/api#webhookv2status-type)optionalState of the webhook, including any error state it may be in |
| description | StringoptionalUser provided description or name for the webhook. Max length 150 characters. |
| Error codes | Description |
| ----------- | ------------------------------------- |
| 400 | Required parameter missing or invalid |
Return value
```
The WebhookV2 that was successfully posted
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -X POST -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
GET webhook
Returns the [WebhookV2](https://www.figma.com/developers/api#webhookv2-type) corresponding to the ID provided, if it exists.
HTTP Endpoint
GET/v2/webhooks/:webhook\_id
| Path parameters | Description |
| --------------- | ------------------------------------------------- |
| webhook\_id | StringThe id of the webhook you want to query for |
| Error codes | Description |
| ----------- | ---------------------------------------------------------------------------- |
| 404 | Webhook does not exist or you do not have permissions to access this webhook |
Return value
```
The WebhookV2 requested
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
PUT webhook
Updates the webhook with the specified properties.
HTTP Endpoint
PUT/v2/webhooks/:webhook\_id
| Path parameters | Description |
| --------------- | ---------------------------------------------- |
| webhook\_id | StringThe id of the webhook you want to update |
| Body parameters | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| event\_type | [WebhookV2Event](https://www.figma.com/developers/api#webhookv2event-type)optionalThe type of event that will trigger this webhook to fire |
| endpoint | StringoptionalThe HTTP endpoint that will receive a POST request when the event triggers |
| passcode | StringoptionalString that will be passed back to your webhook endpoint to verify that it is being called by Figma |
| status | [WebhookStatus](https://www.figma.com/developers/api#webhookstatus-type)optionalState to put the webhook in, either to make the webhook ACTIVE or PAUSED. The webhook cannot be put into an error state this way. |
| description | StringoptionalUser provided description or name for the webhook. Max length 140 characters. Providing a description '' (empty string) will delete the description. |
| Error codes | Description |
| ----------- | ---------------------------------------------------------------------------- |
| 400 | Required parameter missing or invalid |
| 404 | Webhook does not exist or you do not have permissions to access this webhook |
Return value
```
The WebhookV2 that was successfully updated
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -X PUT -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
DELETE webhook
Deletes the specified webhook. This operation cannot be reversed.
HTTP Endpoint
DELETE/v2/webhooks/:webhook\_id
| Path parameters | Description |
| --------------- | ---------------------------------------------- |
| webhook\_id | StringThe id of the webhook you want to delete |
| Error codes | Description |
| ----------- | ---------------------------------------------------------------------------- |
| 400 | Required parameter missing or invalid |
| 404 | Webhook does not exist or you do not have permissions to access this webhook |
Return value
```
The WebhookV2 that was successfully deleted
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -X DELETE -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
GET team webhooks
Returns all webhooks registered under the specified team.
HTTP Endpoint
GET/v2/teams/:team\_id/webhooks
| Path parameters | Description |
| --------------- | --------------------------------------- |
| team\_id | StringThe team id you wish to query for |
Return value
```
{ "webhooks": WebhookV2[]}
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
GET webhook requests
Returns all webhook requests sent within the last week. Useful for debugging.
HTTP Endpoint
GET/v2/webhooks/:webhook\_id/requests
| Path parameters | Description |
| --------------- | ------------------------------------------------- |
| webhook\_id | StringThe id of the webhook you wish to query for |
Return value
```
{ "requests": WebhookV2Request[]}
```
Try it out for yourself+ Get personal access token[What's this?](https://www.figma.com/developers/api#access-tokens)Your cURL commandcurl -H 'X-FIGMA-TOKEN: \' ' API Request
```
Loading...
```
Security
### Securing your webhook
IMPORTANT: When creating a webhook you are required to pass in a passcode. The purpose of the passcode field is so that your application can verify that Figma is actually what is calling your endpoint (as opposed to some attacker trying to make you believe something about your users' Figma files).
We would recommend comparing the passcode we pass back to you with the passcode originally provided when creating the endpoint to make sure they match before acting on the webhook trigger. If you receive a request with the wrong passcode, you should respond with a 400 Bad Request HTTP response which will immediately stop the webhook.Errors
This section outlines the common error codes and resolutions you may encounter while using the Figma API.
| Error code | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400Bad request | Parameters are invalid or malformed. Please check the input formats. |
| 404Not found | The requested file or resource was not found. |
| 429Rate limit | In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute). |
| 500Internal server error | This most commonly occurs for very large image render requests, which may time out our server and return a 500. Please reduce the number and size of objects requested. |