Create Webhook

Create a webhook subscription for a team. Figma will send HTTP POST requests to your endpoint when events occur.

POST https://api.figma.com/v2/webhooks

Authentication

Requires a valid access token with webhooks:write scope. Pass via X-Figma-Token header (personal access token) or Authorization: Bearer header (OAuth).

Setup Workflow

Prepare your endpoint

Set up an HTTPS endpoint on your server that can receive POST requests. The endpoint must respond with a 200 status code within 10 seconds.

Generate a passcode

Create a secret passcode string. Figma includes this in webhook payloads so you can verify that incoming requests are authentic.

Choose your event type

Decide which event to subscribe to. Available event types are listed in the request body parameters below.

Send the POST request with your configuration. Figma will return the webhook details with an ACTIVE status if registration succeeds.

Request Body

Field	Type	Required	Description
`event_type`	`string`	Yes	The event to subscribe to
`team_id`	`string`	Yes	The team ID to watch
`endpoint`	`string`	Yes	HTTPS URL to receive webhooks
`passcode`	`string`	Yes	Secret passcode for verification
`description`	`string`	No	Human-readable description

Show Available event types

| Event Type | Triggered When | |------------|----------------| | FILE_UPDATE | A file in the team is saved | | FILE_DELETE | A file in the team is deleted | | FILE_VERSION_UPDATE | A named version is created | | FILE_COMMENT | A comment is posted on a file | | LIBRARY_PUBLISH | A library is published |

Example Request

curl -X POST "https://api.figma.com/v2/webhooks" \
  -H "X-Figma-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "FILE_UPDATE",
    "team_id": "123456",
    "endpoint": "https://your-server.com/webhooks/figma",
    "passcode": "your-secret-passcode",
    "description": "File update notifications"
  }'

Response

{
  "id": "wh_123456",
  "event_type": "FILE_UPDATE",
  "team_id": "123456",
  "endpoint": "https://your-server.com/webhooks/figma",
  "status": "ACTIVE",
  "description": "File update notifications",
  "created_at": "2024-01-15T10:30:00Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique webhook identifier
`event_type`	`string`	The subscribed event type
`team_id`	`string`	The team being watched
`endpoint`	`string`	The registered endpoint URL
`status`	`string`	Webhook status: `ACTIVE` or `PAUSED`
`description`	`string`	The description you provided
`created_at`	`string`	ISO 8601 timestamp of creation

Your endpoint must be HTTPS and respond with a 200 status within 10 seconds. Figma will disable webhooks that consistently fail to respond.

Use the passcode field in incoming webhook payloads to verify that requests are genuinely from Figma. Compare the passcode in each payload against the one you registered.