Figma Webhooks V2の使い方｜更新・コメント通知と受信確認

FigmaのWebhooks V2は、コメントやファイル更新などのイベントを、指定したサーバーへHTTP POSTで通知する機能です。FILE_UPDATEは編集のたびに即時通知する機能ではなく、編集が止まってから30分以内に発生します。 コメント通知にはFILE_COMMENTを選びます。

この記事では、通知対象の選び方、登録JSON、passcodeの確認、PING・再送・送信履歴による切り分けを説明します。2026年10月3日の公式仕様に基づく解説で、実際のWebhook登録や公開サーバーへの配信は未検証です。Webhooks V2の概要

通知対象と権限を決める

Webhookはチーム・フォルダー・ファイルのいずれかへ登録します。フォルダーは旧称がprojectだったため、APIのcontextは現在もprojectです。新しいフォルダーAPIの名前に合わせてfolderへ変更しないでください。

ファイル単位では、プランごとの総登録数にも上限があります。チーム単位の通知は、招待制フォルダーのファイルを対象にしません。最初は権限を確認できる1ファイル・1イベントで配信経路を確認すると、対象範囲の誤りを切り分けられます。対象・権限・上限

トークンには登録・更新用のwebhooks:write、一覧・送信履歴用のwebhooks:readを付けます。スコープだけで不足しているファイル権限を補うことはできません。個人アクセストークンの取得

イベントを選ぶ

PINGは登録時の疎通確認イベントです。通常の変更通知として購読するイベントと混同しないでください。また、フォルダー自体を削除しても、その中の全ファイルについてFILE_DELETEが届くわけではありません。公式イベント仕様

受信先を用意する

Figmaから到達できるHTTPSの受信URLを用意します。ローカルPCのlocalhostだけでは届きません。開発用トンネルを使う場合は公開範囲を確認し、本番の受信URLと分けて管理します。

受信処理は、JSONを読み、passcodeを照合してから対象イベントを処理する順序にします。通知本文を丸ごとアクセスログに保存するとpasscodeも残るので、処理に必要な識別子と結果だけを記録します。

1. JSONの形式と必要な項目を確認します。
2. passcodeを、登録時に安全に保管した値と照合します。
3. PINGなら疎通確認として応答します。
4. 対象イベントを永続キューなどへ受け渡してから200 OKを返します。
5. 時間のかかるAPI取得や外部連携は、受信応答と分けて処理します。

これは受信処理の設計例です。永続化前に200を返すと、その後の処理失敗をFigma側の再送では回復できません。Webhook IDは購読のIDなので、それだけを重複排除キーにすると別のイベントまで捨ててしまいます。イベントの種類、ファイル、日時や内容に応じて、同じ通知を再処理しても結果が重複しない設計にします。

Webhookを登録するJSON

POST https://api.figma.com/v2/webhooksへ、認証ヘッダーとJSONを送ります。次はコメント通知の構成例です。FILE_KEY、受信URL、passcodeは自分の環境に合わせて置き換えます。ここに記載した値で実際の登録は行っていません。

{
  "event_type": "FILE_COMMENT",
  "context": "file",
  "context_id": "FILE_KEY",
  "endpoint": "https://example.com/figma-hook",
  "passcode": "REPLACE_WITH_A_PRIVATE_RANDOM_VALUE"
}

作成すると通常はPINGが送られます。受信環境がまだ用意できていない場合はstatusをPAUSEDとして作り、準備後に更新します。登録結果のWebhook IDは、一覧照会・送信履歴・停止に使うので保存してください。登録と管理API

passcodeが一致しない場合の扱い

公式は、passcodeが一致しない要求へ400 Bad Requestを返すよう案内しています。この400はWebhookを直ちに停止させる扱いなので、設定ミスで正規の通知を拒否していないかも確認します。

GETでWebhookを取得したとき、passcodeは空文字として伏せられます。登録値が消失したと判断して、受信時に空文字との比較へ切り替えないでください。作成時の値をサーバー側で保持します。passcodeはAPIトークンとは別の、通知元を確認するための値です。公式セキュリティ仕様

FILE_COMMENTの本文を扱う

Webhookのコメント本文は、REST APIで取得する文字列と同じ形式ではありません。comment配列のテキスト断片とメンション情報を確認し、配列をそのまま文字列として扱わないようにします。

スレッドを一覧化したい場合は、必要に応じてコメントのREST APIで取得します。通知を受けたたびに全ファイルを連続取得する構成ではなく、イベントが示すファイルへ処理範囲を限定します。

通知が届かない場合の確認順

1. 登録結果・status・event_type・context_idを確認します。
2. 作成時のPINGと受信サーバーのHTTP結果を確認します。
3. GET /v2/webhooks/:webhook_id/requestsで直近1週間の送信履歴を確認します。
4. 送信履歴がない場合は、対象イベント・権限・招待制フォルダー・FILE_UPDATEの待ち条件を確認します。
5. 送信が失敗している場合は、公開URL、HTTPS、応答時間、HTTPコード、passcodeを確認します。

受信失敗時は3回再送されます。待ち時間は最初の失敗後5分、2回目の失敗後30分、3回目の失敗後3時間です。待ち時間は最初からの累計ではありません。再送があることを前提に、同じ通知で外部処理を重複実行しないようにします。再送の仕様

一覧・停止・削除

一時的に通知を止めたい場合は、削除する前にPAUSEDの利用を検討します。旧チーム専用の一覧APIではなく、現行のGET /v2/webhooksを使います。APIはTier 2に分類されるため、429の扱いはREST APIの制限も確認してください。