【入門編】PenpotのWebhooksとAPI連携入門：デザイン変更を自動検知して通知・管理する方法 – UI/UX・デザインツール活用バイブル

こんにちは！デザインシステムの構築からフロントエンドの実装まで、プロダクトの全レイヤーを美しく繋ぐことに情熱を燃やしているエンジニアの先輩です。

日々の開発現場で、こんなストレスを感じたことはありませんか？
「デザイナーがFigmaやPenpotでコンポーネントを修正したのに、エンジニアへの共有漏れで実装が古いままになっていた」
「デザインの変更履歴を追うために、わざわざツールを開いて確認するのが面倒くさい」

これを解決するのが、今回解説する「PenpotのWebhooksとAPI連携」です。

Figmaがクローズドなエコシステムであるのに対し、オープンソース（OSS）であるPenpotは、その圧倒的な拡張性が魅力です。APIとWebhooksを使いこなせば、「デザインの変更」をトリガーにして、Slackへの通知やGitHubのIssue自動作成などを完全に自動化できます。

これをマスターすれば、毎日の作業が劇的に楽になりますよ。さあ、デザインとコードの境界線を溶かす冒険に出発しましょう！

—

1. なぜPenpotなのか？— 拡張性という名のチートコード

プロダクト開発において、デザインとコードの乖離は永遠の課題です。多くのデザインツールは「見て、手動で真似して作る」というワークフローを強制してきます。

しかし、PenpotはオープンソースのWebベース・デザインツールであり、ファーストクラスでAPIとWebhooksをサポートしています。つまり、私たちが使い慣れたGitHub ActionsやNode.js、Slackといった開発エコシステムと、デザインデータをダイレクトに接続できるのです。

今回のゴールは、「Penpotでデザインに何らかの変更があった瞬間、それをWebhookで検知し、API経由で詳細データを取得してSlackに通知する」という仕組みの基礎を構築することです。

—

2. 基礎セットアップ：Penpot APIの扉を開く

まずは、Penpotと外部プログラムが会話するための「パスポート」を手に入れましょう。

Step 1: アクセス・トークンの生成

Penpotは現在、Self-hosted（セルフホスト）版、または公式のCloud版（penpot.app）で利用できます。APIを利用するには、アカウントの設定からアクセストークンを発行する必要があります。

1. Penpotの右上のプロフィールアイコンから 「Profile」 を開く。
2. 「Access Tokens」 セクションへ移動。
3. トークンに名前（例: `Dev-Automation-Bot`）をつけ、生成する。
4. 発行されたトークンは二度と表示されないため、環境変数 (`PENPOT_TOKEN`) として安全に保管してください。

Step 2: エンドポイントの確認

PenpotのAPIはGraphQLをベースに構築されているか、RESTライクなエンドポイントが整備されています。セルフホストしている場合、ベースURLは通常 `http://localhost:9001/api` のようになります（Cloud版の場合は `https://design.penpot.app/api`）。

—

3. Hello World：API経由でプロジェクト情報を取得してみよう

まずは、PenpotのAPIが正常に動作するかを確かめる「Hello World」ならぬ「Hello Penpot」スクリプトを書きましょう。Node.js環境を想定して、モダンな `fetch` APIを使ったシンプルなスクリプトを作成します。

以下のコードを `test-penpot.js` として保存してください。

/

  • Hello Penpot: API疎通確認スクリプト
  • 実行方法:
  • PENPOT_TOKEN=”あなたのトークン” node test-penpot.js

/

const PENPOT_API_URL = ‘https://design.penpot.app/api/rpc’; // Cloud版の場合
const TOKEN = process.env.PENPOT_TOKEN;

async function getMe() {
if (!TOKEN) {
console.error(‘❌ エラー: PENPOT_TOKEN 環境変数が設定されていません。’);
process.exit(1);
}

try {
console.log(‘🔄 Penpot APIに接続中…’);

// Penpotのバックエンド（Runtimes/RPC）へリクエストを送信
const response = invoker(); // 擬似的な表現。実際は適切なGraphQL/RPCクエリを投げます

// わかりやすいようにREST風のフェッチ例に置き換えます
const res = await fetch(‘https://design.penpot.app/api/rpc’, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/json’,
‘Authorization’: `Bearer ${TOKEN}`
},
body: JSON.stringify({
// ユーザー情報を取得するRPCクエリの例
name: ‘get-current-user’
})
});

if (!res.ok) {
throw new Error(`HTTP error! status: ${res.status}`);
}

const data = await res.json();
console.log(‘✨ 接続成功！現在のユーザー情報:’, data);

} catch (error) {
console.error(‘❌ API通信に失敗しました:’, error.message);
}
}

getMe();

これがAPI連携の第一歩です。このリクエストが通れば、Penpot内のあらゆるファイルやチーム情報にアクセスする権利を手に入れたことになります。

—

4. Webhooksの核心：デザイン変更をリアルタイムでキャッチする

次に、本丸である Webhooks です。Webhooksとは、「何かイベントが起きたら、指定したURL（サーバー）へ自動的にデータをPOSTする」という仕組みです。

Penpotのプロジェクトでファイルが更新されたり、コメントが追加されたりすると、Penpotサーバーがあなたの用意したエンドポイントへ通知を飛ばしてくれます。

Webhook受信用サーバーの構築（Node.js + Express）

デザイン変更の通知を受け取るための軽量なサーバーを、Expressを使ってサクッと立ててみましょう。

`server.js` を作成します。

/

  • Penpot Webhook サーバー
  • デザイナーが変更を加えた瞬間、このサーバーがイベントをキャッチします。

/

const express = require(‘express’);
const app = express();
const PORT = process.ended?.PORT || 3000;

// JSONペイロードを正しく解析するためのミドルウェア
app.use(express.json());

// Webhookの受け口（エンドポイント）
app.post(‘/webhook/penpot’, (req, res) => {
const event = req.body;

console.log(‘🔔 PenpotからWebhookを受信しました！’);

// イベントの種類に応じた処理の分岐
switch (event.type) {
case ‘file.updated’:
console.log(`📁 ファイル “${event.fileName}” が更新されました。`);
// ここでSlackへ通知を送る関数を呼ぶなどの処理を記述できます
break;

case ‘comment.created’:
console.log(`💬 新しいコメントが追加されました: “${event.commentText}”`);
break;

default:
console.log(`ℹ️ その他のイベント: ${event.type}`);
}

// 正常に受信したことをPenpotサーバーに素早く返す（タイムアウト防衛）
res.status(200).json({ status: ‘received’ });
});

app.listen(PORT, () => {
console.log(`🚀 Webhook サーバーがポート ${PORT} で起動しました`);
});

ローカル開発時の注意点：Ngrokの活用

あなたのPC（`localhost`）上でこのサーバーを動かしている場合、インターネット上のPenpotサーバーからアクセスすることはできません。
そこで、Ngrok などのトンネリングツールを使用します。

ngrok http 3000

生成されたパブリックURL（例: `https://xxxx.ngrok-free.app/webhook/penpot`）を、Penpotのプロジェクト設定にあるWebhook登録画面に入力すれば準備完了です！

—

5. 実践的な活用アイデア：デザイン変更をSlackへ通知する

ここまでくれば、あとは料理のバリエーション次第です。例えば、先ほどのWebhookサーバーに Slack Webhook（Incoming Webhook） を組み合わせてみましょう。

const SLACK_WEBHOOK_URL = ‘https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK’;

async function notifyToSlack(message) {
await fetch(SLACK_WEBHOOK_URL, {
method: ‘POST’,
headers: { ‘Content-Type’: ‘application/json’ },
body: JSON.stringify({
text: `🎨 Penpot Automation Bot\n${message}`
})
});
}

これを `file.updated` のイベント内に組み込むだけで、チーム全員が参加しているSlackチャンネルに「〇〇のファイルが更新されました！」とリアルタイムで飛ぶようになります。

  • 「朝会で『どこ変わったっけ？』と探す時間がゼロになる」
  • 「エンジニアが最新のデザイン差分にいち早く気づき、手戻りが減る」

この小さな自動化の積み重ねが、チームの生産性を爆発的に引き上げるのです。

—

6. おわりに：ツールに使われるな、ツールをハックしろ

今回はPenpotのAPIとWebhooksの基本、そして外部ツールと連携させるための基礎セットアップとコード解説を行いました。

オープンソースであるPenpotの最大の強みは、「自分たちの開発フローに合わせて、ツール側をカスタマイズできる」という自由度の高さにあります。既製品の仕様にフラストレーションを溜め込む時代は終わりです。

ぜひ今回のコードをベースに、あなたのチームのワークフローに合わせた「最強の自動化パイプライン」を組んでみてください。毎日の作業が劇的に、そして圧倒的に楽しくなりますよ！

それでは、次のハックでお会いしましょう。Happy Coding & Designing!

スポンサーリンク
タイトルとURLをコピーしました